From 5717000ba665460cffacb69fd3a7bef2b2666465 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 03:28:08 +0000
Subject: [PATCH 01/11] feat(evmigration): harden operator provenance
 safeguards

---
 .../compatibility-manifest.schema.json        | 342 +++++++++++++++++
 .../compatibility-manifest.template.json      | 151 ++++++++
 .../owned-testnet-baseline.template.json      |  76 ++++
 docs/evm-integration/user-guides/migration.md |   2 +
 .../user-guides/operator-migration-runbook.md | 363 ++++++++++++++++++
 .../user-guides/relayer-migration.md          |  77 ++--
 .../user-guides/supernode-migration.md        |  17 +-
 .../user-guides/validator-migration.md        |  31 +-
 scripts/evmigration-common.sh                 |  88 ++++-
 scripts/migrate-account.sh                    |   2 +-
 scripts/migrate-validator.sh                  |   2 +-
 tests/scripts/common.bats                     | 121 ++++++
 tests/scripts/fixtures/lumerad-shim.sh        |   7 +
 tests/scripts/migrate-account.bats            |  41 ++
 tests/scripts/migrate-batch.bats              |   5 +
 15 files changed, 1257 insertions(+), 68 deletions(-)
 create mode 100644 docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
 create mode 100644 docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
 create mode 100644 docs/evm-integration/operator-artifacts/owned-testnet-baseline.template.json
 create mode 100644 docs/evm-integration/user-guides/operator-migration-runbook.md

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
new file mode 100644
index 00000000..bcc6da0a
--- /dev/null
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lumera.io/schemas/evmigration-compatibility-manifest-v1.json",
+  "title": "Lumera EVM migration compatibility manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schema_version",
+    "release",
+    "chain",
+    "artifacts",
+    "operator_contracts",
+    "validation",
+    "approval"
+  ],
+  "properties": {
+    "$schema": { "const": "./compatibility-manifest.schema.json" },
+    "schema_version": { "const": "1.0.0" },
+    "release": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tag", "commit", "release_url"],
+      "properties": {
+        "tag": { "type": "string", "minLength": 1 },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "release_url": { "type": "string", "minLength": 1 }
+      }
+    },
+    "chain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chain_id", "evm_chain_id", "minimum_upgrade"],
+      "properties": {
+        "chain_id": { "type": "string", "minLength": 1 },
+        "evm_chain_id": { "type": ["integer", "string"] },
+        "minimum_upgrade": { "type": "string", "minLength": 1 }
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["chain_executable", "supernode_executable", "bound_files"],
+      "properties": {
+        "chain_executable": { "$ref": "#/$defs/executable" },
+        "supernode_executable": { "$ref": "#/$defs/executable" },
+        "bound_files": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "scripts/evmigration-common.sh",
+            "scripts/migrate-account.sh",
+            "scripts/migrate-validator.sh",
+            "scripts/migrate-multisig.sh",
+            "scripts/migrate-batch.sh",
+            "docs/evm-integration/user-guides/operator-migration-runbook.md",
+            "docs/evm-integration/user-guides/migration.md",
+            "docs/evm-integration/user-guides/migration-scripts.md",
+            "docs/evm-integration/user-guides/validator-migration.md",
+            "docs/evm-integration/user-guides/supernode-migration.md",
+            "docs/evm-integration/user-guides/relayer-migration.md",
+            "docs/evm-integration/evmigration/legacy-migration.md"
+          ],
+          "properties": {
+            "scripts/evmigration-common.sh": { "$ref": "#/$defs/file" },
+            "scripts/migrate-account.sh": { "$ref": "#/$defs/file" },
+            "scripts/migrate-validator.sh": { "$ref": "#/$defs/file" },
+            "scripts/migrate-multisig.sh": { "$ref": "#/$defs/file" },
+            "scripts/migrate-batch.sh": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/operator-migration-runbook.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/migration.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/migration-scripts.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/validator-migration.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/supernode-migration.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/user-guides/relayer-migration.md": { "$ref": "#/$defs/file" },
+            "docs/evm-integration/evmigration/legacy-migration.md": { "$ref": "#/$defs/file" }
+          }
+        }
+      }
+    },
+    "operator_contracts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["binary_provenance", "keyring_provenance", "destination_prestage_no_echo", "single_broadcast"],
+      "properties": {
+        "binary_provenance": { "const": "absolute-path+version+sha256" },
+        "keyring_provenance": { "const": "backend-and-location-separated" },
+        "destination_prestage_no_echo": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "implementation"],
+          "properties": {
+            "status": { "enum": ["verified", "blocked"] },
+            "implementation": {
+              "oneOf": [
+                { "type": "null" },
+                { "$ref": "#/$defs/pr2_implementation" }
+              ]
+            }
+          }
+        },
+        "single_broadcast": { "const": true }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bats", "shellcheck", "cli_help", "schema", "json_parse", "docs_links", "owned_testnet", "portal_live"],
+      "properties": {
+        "bats": { "$ref": "#/$defs/check" },
+        "shellcheck": { "$ref": "#/$defs/check" },
+        "cli_help": { "$ref": "#/$defs/check" },
+        "schema": { "$ref": "#/$defs/check" },
+        "json_parse": { "$ref": "#/$defs/check" },
+        "docs_links": { "$ref": "#/$defs/check" },
+        "owned_testnet": { "$ref": "#/$defs/check" },
+        "portal_live": { "$ref": "#/$defs/check" }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "release_owner_approved", "canonicalization", "detached_signature"],
+      "properties": {
+        "status": { "enum": ["approved", "blocked"] },
+        "release_owner_approved": { "type": "boolean" },
+        "canonicalization": { "const": "RFC8785-JCS" },
+        "detached_signature": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["format", "bundle", "certificate_identity", "certificate_oidc_issuer"],
+          "properties": {
+            "format": { "const": "sigstore-bundle" },
+            "bundle": { "const": "compatibility-manifest.sigstore.json" },
+            "certificate_identity": { "type": ["string", "null"] },
+            "certificate_oidc_issuer": { "type": ["string", "null"] }
+          }
+        }
+      }
+    },
+    "_verification": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "_signing_blocker": { "type": "string", "minLength": 1 }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "approval": {
+            "required": ["status"],
+            "properties": { "status": { "const": "approved" } }
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "release": {
+            "properties": {
+              "tag": { "$ref": "#/$defs/non_placeholder" },
+              "commit": { "$ref": "#/$defs/commit" },
+              "release_url": { "$ref": "#/$defs/non_placeholder" }
+            }
+          },
+          "chain": {
+            "properties": {
+              "chain_id": { "$ref": "#/$defs/non_placeholder" },
+              "evm_chain_id": {
+                "oneOf": [
+                  { "type": "integer", "minimum": 1 },
+                  { "$ref": "#/$defs/non_placeholder" }
+                ]
+              },
+              "minimum_upgrade": { "$ref": "#/$defs/non_placeholder" }
+            }
+          },
+          "artifacts": { "$ref": "#/$defs/approved_artifacts" },
+          "operator_contracts": {
+            "properties": {
+              "destination_prestage_no_echo": {
+                "properties": {
+                  "status": { "const": "verified" },
+                  "implementation": { "$ref": "#/$defs/approved_pr2_implementation" }
+                }
+              }
+            }
+          },
+          "validation": {
+            "properties": {
+              "bats": { "$ref": "#/$defs/passing_check" },
+              "shellcheck": { "$ref": "#/$defs/passing_check" },
+              "cli_help": { "$ref": "#/$defs/passing_check" },
+              "schema": { "$ref": "#/$defs/passing_check" },
+              "json_parse": { "$ref": "#/$defs/passing_check" },
+              "docs_links": { "$ref": "#/$defs/passing_check" },
+              "owned_testnet": { "$ref": "#/$defs/passing_check" },
+              "portal_live": { "$ref": "#/$defs/passing_check" }
+            }
+          },
+          "approval": {
+            "properties": {
+              "release_owner_approved": { "const": true },
+              "detached_signature": { "$ref": "#/$defs/approved_signature" }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "non_placeholder": {
+      "type": "string",
+      "minLength": 3,
+      "pattern": "^(?!REPLACE(?:_|$))(?!.*<[^>]+>)(?!PLACEHOLDER$)(?!TBD$)(?!TODO$)(?!UNKNOWN$).+\\S$"
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^(?!0{64}$)[0-9a-f]{64}$"
+    },
+    "commit": {
+      "type": "string",
+      "pattern": "^(?!0{40}$)[0-9a-f]{40}$"
+    },
+    "file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sha256", "source"],
+      "properties": {
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "approved_file": {
+      "type": "object",
+      "properties": {
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "source": { "$ref": "#/$defs/non_placeholder" }
+      }
+    },
+    "executable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "release_path", "version", "tag", "commit", "sha256", "source"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "release_path": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "tag": { "type": "string", "minLength": 1 },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "approved_executable": {
+      "type": "object",
+      "properties": {
+        "name": { "$ref": "#/$defs/non_placeholder" },
+        "release_path": { "$ref": "#/$defs/non_placeholder" },
+        "version": { "$ref": "#/$defs/non_placeholder" },
+        "tag": { "$ref": "#/$defs/non_placeholder" },
+        "commit": { "$ref": "#/$defs/commit" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "source": { "$ref": "#/$defs/non_placeholder" }
+      }
+    },
+    "pr2_implementation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "tag", "commit", "sha256", "source", "no_echo_contract"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "tag": { "type": "string", "minLength": 1 },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "source": { "type": "string", "minLength": 1 },
+        "no_echo_contract": { "const": "hidden-tty-or-protected-fd;never-argv;never-echo;no-xtrace" }
+      }
+    },
+    "approved_pr2_implementation": {
+      "allOf": [
+        { "$ref": "#/$defs/pr2_implementation" },
+        {
+          "properties": {
+            "name": { "$ref": "#/$defs/non_placeholder" },
+            "tag": { "$ref": "#/$defs/non_placeholder" },
+            "commit": { "$ref": "#/$defs/commit" },
+            "sha256": { "$ref": "#/$defs/sha256" },
+            "source": { "$ref": "#/$defs/non_placeholder" }
+          }
+        }
+      ]
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "evidence"],
+      "properties": {
+        "status": { "enum": ["pass", "fail", "postponed"] },
+        "evidence": { "type": "string" }
+      }
+    },
+    "passing_check": {
+      "type": "object",
+      "properties": {
+        "status": { "const": "pass" },
+        "evidence": { "$ref": "#/$defs/non_placeholder" }
+      }
+    },
+    "approved_signature": {
+      "type": "object",
+      "properties": {
+        "certificate_identity": { "$ref": "#/$defs/non_placeholder" },
+        "certificate_oidc_issuer": { "$ref": "#/$defs/non_placeholder" }
+      }
+    },
+    "approved_artifacts": {
+      "type": "object",
+      "properties": {
+        "chain_executable": { "$ref": "#/$defs/approved_executable" },
+        "supernode_executable": { "$ref": "#/$defs/approved_executable" },
+        "bound_files": {
+          "properties": {
+            "scripts/evmigration-common.sh": { "$ref": "#/$defs/approved_file" },
+            "scripts/migrate-account.sh": { "$ref": "#/$defs/approved_file" },
+            "scripts/migrate-validator.sh": { "$ref": "#/$defs/approved_file" },
+            "scripts/migrate-multisig.sh": { "$ref": "#/$defs/approved_file" },
+            "scripts/migrate-batch.sh": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/operator-migration-runbook.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/migration.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/migration-scripts.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/validator-migration.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/supernode-migration.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/user-guides/relayer-migration.md": { "$ref": "#/$defs/approved_file" },
+            "docs/evm-integration/evmigration/legacy-migration.md": { "$ref": "#/$defs/approved_file" }
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
new file mode 100644
index 00000000..5cdbf69d
--- /dev/null
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -0,0 +1,151 @@
+{
+  "$schema": "./compatibility-manifest.schema.json",
+  "schema_version": "1.0.0",
+  "release": {
+    "tag": "REPLACE_WITH_RELEASE_TAG",
+    "commit": "0000000000000000000000000000000000000000",
+    "release_url": "REPLACE_WITH_RELEASE_URL"
+  },
+  "chain": {
+    "chain_id": "REPLACE_WITH_CHAIN_ID",
+    "evm_chain_id": "REPLACE_WITH_EVM_CHAIN_ID",
+    "minimum_upgrade": "REPLACE_WITH_UPGRADE_NAME"
+  },
+  "artifacts": {
+    "chain_executable": {
+      "name": "lumerad",
+      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_LUMERAD",
+      "version": "REPLACE_WITH_LUMERAD_VERSION_LONG",
+      "tag": "REPLACE_WITH_CHAIN_RELEASE_TAG",
+      "commit": "0000000000000000000000000000000000000000",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET_URL"
+    },
+    "supernode_executable": {
+      "name": "supernode",
+      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_SUPERNODE",
+      "version": "REPLACE_WITH_SUPERNODE_VERSION",
+      "tag": "REPLACE_WITH_SUPERNODE_RELEASE_TAG",
+      "commit": "0000000000000000000000000000000000000000",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "source": "REPLACE_WITH_SUPERNODE_RELEASE_ASSET_URL"
+    },
+    "bound_files": {
+      "scripts/evmigration-common.sh": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/evmigration-common.sh"
+      },
+      "scripts/migrate-account.sh": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-account.sh"
+      },
+      "scripts/migrate-validator.sh": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-validator.sh"
+      },
+      "scripts/migrate-multisig.sh": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-multisig.sh"
+      },
+      "scripts/migrate-batch.sh": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-batch.sh"
+      },
+      "docs/evm-integration/user-guides/operator-migration-runbook.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/operator-migration-runbook.md"
+      },
+      "docs/evm-integration/user-guides/migration.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration.md"
+      },
+      "docs/evm-integration/user-guides/migration-scripts.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration-scripts.md"
+      },
+      "docs/evm-integration/user-guides/validator-migration.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/validator-migration.md"
+      },
+      "docs/evm-integration/user-guides/supernode-migration.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/supernode-migration.md"
+      },
+      "docs/evm-integration/user-guides/relayer-migration.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/relayer-migration.md"
+      },
+      "docs/evm-integration/evmigration/legacy-migration.md": {
+        "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+        "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/evmigration/legacy-migration.md"
+      }
+    }
+  },
+  "operator_contracts": {
+    "binary_provenance": "absolute-path+version+sha256",
+    "keyring_provenance": "backend-and-location-separated",
+    "destination_prestage_no_echo": {
+      "status": "blocked",
+      "implementation": null
+    },
+    "single_broadcast": true
+  },
+  "validation": {
+    "bats": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_COMMAND_AND_SANITIZED_RESULT"
+    },
+    "shellcheck": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_COMMAND_AND_SANITIZED_RESULT"
+    },
+    "cli_help": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_HELP_COMMANDS_AND_BINARY_HASHES"
+    },
+    "schema": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_SCHEMA_TEMPLATE_AND_UNSAFE_APPROVAL_RESULTS"
+    },
+    "json_parse": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_JSON_PARSE_RESULT"
+    },
+    "docs_links": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_LINK_CHECK_RESULT"
+    },
+    "owned_testnet": {
+      "status": "postponed",
+      "evidence": "owned-testnet-baseline.template.json"
+    },
+    "portal_live": {
+      "status": "postponed",
+      "evidence": "REPLACE_WITH_REDACTED_LIVE_BROWSER_EVIDENCE_BUNDLE"
+    }
+  },
+  "approval": {
+    "status": "blocked",
+    "release_owner_approved": false,
+    "canonicalization": "RFC8785-JCS",
+    "detached_signature": {
+      "format": "sigstore-bundle",
+      "bundle": "compatibility-manifest.sigstore.json",
+      "certificate_identity": null,
+      "certificate_oidc_issuer": null
+    }
+  },
+  "_verification": [
+    "Release owner: replace every REPLACE_WITH value and every all-zero commit/hash; approval.status=approved is schema-invalid while any remain.",
+    "Extract each release asset into a new mode-0700 directory. Verify the chain and SuperNode executable tag, commit, version, source, and SHA-256, then verify every artifacts.bound_files entry individually with sha256sum.",
+    "Require operator_contracts.destination_prestage_no_echo.status=verified and bind its implementation name, tag, commit, SHA-256, source, and exact no-echo contract. Do not approve an unfinished or narrative-only PR-2 dependency.",
+    "Run every validation command and attach sanitized evidence. Every validation status, including owned_testnet and portal_live, must be pass before approval is schema-valid.",
+    "Validate the schema under draft 2020-12, validate this manifest against it, and confirm a copy changed to approval.status=approved while retaining any blocked/postponed/placeholder field is rejected.",
+    "Before canonicalization, the release owner MUST set approval.release_owner_approved=true, approval.status=approved, and replace approval.detached_signature certificate_identity/certificate_oidc_issuer with the trusted release identity and issuer. Revalidate the completed draft against the schema; do not edit approval or signature metadata after canonicalization.",
+    "Create the final immutable manifest bytes with RFC 8785 JCS, for example: python3 -c 'import json,sys,rfc8785; sys.stdout.buffer.write(rfc8785.dumps(json.load(sys.stdin)))' < compatibility-manifest.draft.json > compatibility-manifest.json. Do not edit compatibility-manifest.json after canonicalization or signing.",
+    "Use keyless Sigstore signing (no long-lived signing secret): cosign sign-blob --yes --bundle compatibility-manifest.sigstore.json compatibility-manifest.json",
+    "Verify without modifying either file, using the same trusted identity and issuer already embedded before canonicalization: cosign verify-blob --bundle compatibility-manifest.sigstore.json --certificate-identity 'RELEASE_OWNER_MUST_REPLACE_CERTIFICATE_IDENTITY' --certificate-oidc-issuer 'RELEASE_OWNER_MUST_REPLACE_OIDC_ISSUER' compatibility-manifest.json",
+    "Publish compatibility-manifest.json and compatibility-manifest.sigstore.json together. Approval is effective only when schema validation passes and the detached bundle verifies against the release-owner-approved identity and issuer."
+  ],
+  "_signing_blocker": "No release-owner trusted Sigstore certificate identity/OIDC issuer is currently supplied. Keep approval blocked until the release owner supplies them, all external gates pass, the final canonical manifest is signed, and the detached bundle verifies."
+}
diff --git a/docs/evm-integration/operator-artifacts/owned-testnet-baseline.template.json b/docs/evm-integration/operator-artifacts/owned-testnet-baseline.template.json
new file mode 100644
index 00000000..e6f029be
--- /dev/null
+++ b/docs/evm-integration/operator-artifacts/owned-testnet-baseline.template.json
@@ -0,0 +1,76 @@
+{
+  "schema_version": "1.0.0",
+  "classification": "SANITIZED_OWNED_TESTNET_BASELINE",
+  "provenance_status": "POSTPONED",
+  "reason": "Replace placeholders only after an owned-testnet rehearsal; never insert credentials or secret values.",
+  "observed_at_utc": null,
+  "operator": {
+    "organization": "REPLACE_WITH_NON_SECRET_OWNER",
+    "environment": "owned-testnet",
+    "evidence_bundle_sha256": null
+  },
+  "network": {
+    "chain_id": null,
+    "evm_chain_id": null,
+    "genesis_sha256": null,
+    "upgrade_name": null,
+    "height_before": null,
+    "height_after": null
+  },
+  "artifacts": {
+    "release_tag": null,
+    "commit": null,
+    "lumerad_version": null,
+    "lumerad_sha256": null,
+    "helper_sha256": null,
+    "compatibility_manifest_sha256": null,
+    "compatibility_manifest_signature_verified": false
+  },
+  "runtime": {
+    "supervisor": null,
+    "service_user_uid": null,
+    "base_directory_redacted": true,
+    "config_sha256_before": null,
+    "config_sha256_after": null,
+    "keyring_backend": null,
+    "keyring_location_redacted": true
+  },
+  "public_addresses": {
+    "legacy": null,
+    "destination": null,
+    "destination_key_type": null,
+    "migration_record_destination": null
+  },
+  "gates": {
+    "process_discovered": "POSTPONED",
+    "config_backup_mode_0600": "POSTPONED",
+    "destination_no_echo_prestage": "POSTPONED",
+    "destination_freshness": "POSTPONED",
+    "service_stopped_verified": "POSTPONED",
+    "dry_run": "POSTPONED",
+    "single_broadcast": "POSTPONED",
+    "public_chain_queries": "POSTPONED",
+    "grpc_health_serving": "POSTPONED",
+    "logs_reviewed": "POSTPONED",
+    "portal_live_browser_evidence": "POSTPONED"
+  },
+  "transaction": {
+    "tx_hash": null,
+    "height": null,
+    "code": null,
+    "broadcast_attempt_count": 0
+  },
+  "result": "POSTPONED",
+  "redaction_attestation": {
+    "mnemonics_absent": true,
+    "private_keys_absent": true,
+    "passphrases_absent": true,
+    "tokens_cookies_auth_headers_absent": true,
+    "raw_environment_absent": true
+  },
+  "notes": [
+    "Use public chain addresses and hashes only.",
+    "Do not include keyring files, Secret objects, mnemonic argv, terminal history, HAR auth headers, or raw logs before redaction.",
+    "POSTPONED is not PASS and must not be used as release approval evidence."
+  ]
+}
diff --git a/docs/evm-integration/user-guides/migration.md b/docs/evm-integration/user-guides/migration.md
index 8eca3227..aebe3177 100644
--- a/docs/evm-integration/user-guides/migration.md
+++ b/docs/evm-integration/user-guides/migration.md
@@ -3,6 +3,8 @@
 **Last updated**: 2026-06-24
 **Applies to**: Lumera chain with `x/evmigration` module enabled (post-EVM upgrade)
 
+> **Operator/custody gate:** Before any terminal or service migration, follow the canonical [EVM Migration Operator Runbook](operator-migration-runbook.md). It pins executable and keyring provenance, places destination proof before the irreversible boundary, defines stop/restart evidence for systemd/Docker/Kubernetes, and fails closed when release signing or the required PR-2 no-echo destination-prestage dependency is unresolved.
+
 ---
 
 ## Why Migration Is Needed
diff --git a/docs/evm-integration/user-guides/operator-migration-runbook.md b/docs/evm-integration/user-guides/operator-migration-runbook.md
new file mode 100644
index 00000000..fa015a65
--- /dev/null
+++ b/docs/evm-integration/user-guides/operator-migration-runbook.md
@@ -0,0 +1,363 @@
+# EVM Migration Operator Runbook
+
+**Audience:** validators, supernodes, relayers, and custodial account operators
+**Scope:** executable safety gates around the existing migration helpers; this does not replace account-specific guides.
+
+Migration is irreversible after the transaction is included. Record commands and public addresses, but never record mnemonics, private keys, keyring passphrases, bearer tokens, or raw environment dumps.
+
+## 1. Discover the process before changing it
+
+Set an evidence directory on an encrypted operator-controlled volume:
+
+```bash
+umask 077
+EVIDENCE_DIR="$HOME/evmigration-evidence/$(date -u +%Y%m%dT%H%M%SZ)"
+mkdir -p "$EVIDENCE_DIR"
+```
+
+### systemd
+
+```bash
+sudo systemctl show lumerad \
+  -p User -p Group -p FragmentPath -p ExecStart -p WorkingDirectory \
+  | tee "$EVIDENCE_DIR/systemd-lumerad.txt"
+sudo systemctl cat lumerad | tee "$EVIDENCE_DIR/systemd-lumerad-unit.txt"
+```
+
+From `User`, `ExecStart`, and the unit environment, identify the service user, exact executable, `--home`/base directory, config directory, and keyring backend/location. Run all helper/keyring commands as that service user. Do not assume the interactive user's `$HOME` or keyring.
+
+### Docker
+
+```bash
+docker inspect <container> \
+  --format '{{json .Config.User}} {{json .Path}} {{json .Args}} {{json .Mounts}} {{json .Config.Image}}' \
+  | tee "$EVIDENCE_DIR/docker-lumerad.txt"
+docker image inspect <image> --format '{{json .RepoDigests}}' \
+  | tee "$EVIDENCE_DIR/docker-image-digests.txt"
+```
+
+Identify the container user, command/arguments, mounted home/config/keyring paths, and immutable image digest. Run the helper in an image/container with those same mounts and identity.
+
+### Kubernetes
+
+```bash
+kubectl -n <namespace> get statefulset/<name> -o yaml \
+  | tee "$EVIDENCE_DIR/kubernetes-workload.yaml"
+kubectl -n <namespace> get pod <pod> -o jsonpath='{range .spec.containers[*]}{.name}{" user="}{.securityContext.runAsUser}{" command="}{.command}{" args="}{.args}{" mounts="}{.volumeMounts}{"\n"}{end}' \
+  | tee "$EVIDENCE_DIR/kubernetes-runtime.txt"
+```
+
+Identify `runAsUser`, command/args, PVC/config/secret mounts, base directory, and keyring location. The captured YAML is sensitive operational metadata even though it must not contain Secret values; restrict the evidence directory.
+
+## 2. Pin binary, home, and keyring provenance
+
+Use the exact release executable and explicit flags. The helpers resolve `--binary` once to an absolute canonical path, then print that path, the actual `version --long` version, SHA-256, and source before doing key work. They print keyring backend and keyring location separately, with each source.
+
+```bash
+LUMERAD=/absolute/path/to/approved/lumerad
+"$LUMERAD" version --long | tee "$EVIDENCE_DIR/lumerad-version.txt"
+sha256sum "$LUMERAD" | tee "$EVIDENCE_DIR/lumerad.sha256"
+
+sudo -u <service-user> ./scripts/migrate-validator.sh \
+  <legacy-key-name> <destination-key-name> \
+  --binary "$LUMERAD" \
+  --home /absolute/lumera/home \
+  --keyring-backend <test|file|os> \
+  --keyring-dir /absolute/keyring/location \
+  --chain-id <chain-id> \
+  --node <trusted-rpc> \
+  --i-have-stopped-the-node \
+  --dry-run
+```
+
+For a non-validator account, use `migrate-account.sh` and omit `--i-have-stopped-the-node`. Do not continue if the displayed binary, version, checksum, service user, home, backend, or location differs from the approved compatibility manifest.
+
+## 3. Back up configuration (mode 0600)
+
+Back up configuration, not mnemonics or private keys, before stopping:
+
+```bash
+umask 077
+install -m 0600 /absolute/lumera/home/config/config.toml \
+  "$EVIDENCE_DIR/config.toml.before"
+install -m 0600 /absolute/lumera/home/config/app.toml \
+  "$EVIDENCE_DIR/app.toml.before"
+stat -c '%a %U:%G %n' "$EVIDENCE_DIR"/*.before
+sha256sum "$EVIDENCE_DIR"/*.before > "$EVIDENCE_DIR/config-before.sha256"
+```
+
+For a supernode or Hermes relayer, use the discovered config path in place of these examples. Review copies before sharing: endpoints and topology may be sensitive. Never copy keyring contents into this evidence directory.
+
+## 4. Pre-stage and prove the destination before downtime
+
+**Required PR-2 compatibility dependency:** use only the release's approved destination pre-stage operation that implements the PR-2 no-echo contract. That operation must read the mnemonic from a hidden TTY or protected input file descriptor, never from argv, never echo it, never enable shell tracing, and print only non-secret key metadata. This PR-3 runbook does not claim that an unfinished PR-2 command exists in the current binary; if the release compatibility manifest does not name and hash an implementation of this contract, stop.
+
+After PR-2 pre-staging, verify the destination locally using the same binary/home/backend/location:
+
+```bash
+DEST_JSON=$(
+  sudo -u <service-user> "$LUMERAD" keys show <destination-key-name> \
+    --output json \
+    --home /absolute/lumera/home \
+    --keyring-backend <backend> \
+    --keyring-dir /absolute/keyring/location
+)
+printf '%s\n' "$DEST_JSON" | jq '{name,address,type:(.type // .pubkey."@type" // .pubkey.type_url)}'
+DEST_ADDR=$(printf '%s\n' "$DEST_JSON" | jq -er '.address')
+```
+
+The destination must be coin type 60 / `eth_secp256k1`, controlled and recoverable by the operator, and fresh on-chain. Run the helper dry-run and retain its public-address output. It checks key types, migration indexes, destination account freshness, and the migration estimate. A destination mismatch or unknown key type is a hard stop.
+
+## 5. Stop and prove stopped
+
+### systemd
+
+```bash
+sudo systemctl stop lumerad
+sudo systemctl is-active --quiet lumerad && { echo 'lumerad still active' >&2; exit 1; } || true
+sudo systemctl show lumerad -p ActiveState -p SubState -p MainPID
+pgrep -a -u <service-user> -f '(^|/)lumerad( |$)' && { echo 'lumerad process remains' >&2; exit 1; } || true
+```
+
+### Docker
+
+```bash
+docker stop --time 60 <container>
+test "$(docker inspect -f '{{.State.Running}}' <container>)" = false
+docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.FinishedAt}}' <container>
+```
+
+Disable or account for an external restart policy before manual replacement; do not start a second process with the same consensus key.
+
+### Kubernetes
+
+```bash
+kubectl -n <namespace> scale statefulset/<name> --replicas=0
+kubectl -n <namespace> wait --for=delete pod/<pod> --timeout=120s
+! kubectl -n <namespace> get pod -l app=<label> --no-headers 2>/dev/null | grep -q .
+```
+
+Record the original replica count. If an operator manages replicas, pause reconciliation first. Do not continue while any pod with the validator consensus key is running.
+
+## 6. Re-run dry-run, verify destination, broadcast once
+
+Repeat the same dry-run after stopping. Compare its displayed absolute binary path/version/SHA-256 and separate keyring backend/location provenance to the approved manifest. Verify the printed legacy and destination public addresses and destination key type one final time.
+
+The irreversible boundary is the first live helper invocation. Choose the branch that matches the discovered supervisor and run it exactly once. The paths, image digest, service identity, mounts, binary/helper hashes, keyring, and RPC must match the approved manifest and the successful post-stop dry-run.
+
+### systemd / secured operator host
+
+```bash
+sudo -u <service-user> ./scripts/migrate-validator.sh \
+  <legacy-key-name> <destination-key-name> \
+  --binary "$LUMERAD" \
+  --home /absolute/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /absolute/keyring/location \
+  --chain-id <chain-id> \
+  --node <trusted-rpc> \
+  --i-have-stopped-the-node
+```
+
+### Docker one-shot container
+
+Do not apply the systemd command to a container deployment. Keep the original workload container stopped and run a one-shot container from the **manifest-pinned image digest**, as the same numeric UID/GID, with the stopped container's volumes. The image must contain the manifest-pinned helper and binary at the paths below; verify both hashes before use.
+
+```bash
+# The workload container remains stopped for both commands.
+test "$(docker inspect -f '{{.State.Running}}' <stopped-container>)" = false
+APPROVED_IMAGE='<registry>/<image>@sha256:<manifest-image-digest>'
+SERVICE_UID_GID='<uid>:<gid>'
+
+docker run --rm -it --name evmigration-dry-run \
+  --user "$SERVICE_UID_GID" --network host \
+  --volumes-from <stopped-container>:rw \
+  --entrypoint /release/scripts/migrate-validator.sh \
+  "$APPROVED_IMAGE" \
+  <legacy-key-name> <destination-key-name> \
+  --binary /release/bin/lumerad \
+  --home /mounted/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /mounted/keyring/location \
+  --chain-id <chain-id> --node <trusted-rpc> \
+  --i-have-stopped-the-node --dry-run
+
+# After approving the dry-run transcript, run this live command ONCE.
+docker run --rm -it --name evmigration-live \
+  --user "$SERVICE_UID_GID" --network host \
+  --volumes-from <stopped-container>:rw \
+  --entrypoint /release/scripts/migrate-validator.sh \
+  "$APPROVED_IMAGE" \
+  <legacy-key-name> <destination-key-name> \
+  --binary /release/bin/lumerad \
+  --home /mounted/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /mounted/keyring/location \
+  --chain-id <chain-id> --node <trusted-rpc> \
+  --i-have-stopped-the-node
+```
+
+`--network host` is an explicit example for a trusted operator-controlled host. If policy forbids it, attach the one-shot container to an approved network that can reach `<trusted-rpc>`; do not target the stopped container or an untrusted public endpoint.
+
+### Kubernetes one-shot pod
+
+Keep the StatefulSet at zero replicas. Apply a dedicated Pod using the workload's exact `serviceAccountName`, `runAsUser`/`runAsGroup`, PVC, config/keyring mount paths, manifest-pinned image digest, helper, binary, and trusted RPC. Do not mount a validator PVC read-write into any other pod concurrently.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: evmigration-once
+  namespace: <namespace>
+spec:
+  restartPolicy: Never
+  serviceAccountName: <same-service-account-as-stopped-workload>
+  securityContext:
+    runAsUser: <same-runAsUser>
+    runAsGroup: <same-runAsGroup>
+    fsGroup: <same-fsGroup>
+  containers:
+    - name: migrate
+      image: <registry>/<image>@sha256:<manifest-image-digest>
+      imagePullPolicy: IfNotPresent
+      command: ["/release/scripts/migrate-validator.sh"]
+      args:
+        - <legacy-key-name>
+        - <destination-key-name>
+        - --binary
+        - /release/bin/lumerad
+        - --home
+        - /mounted/lumera/home
+        - --keyring-backend
+        - <backend>
+        - --keyring-dir
+        - /mounted/keyring/location
+        - --chain-id
+        - <chain-id>
+        - --node
+        - <trusted-rpc>
+        - --i-have-stopped-the-node
+        - --dry-run
+      stdin: true
+      tty: true
+      volumeMounts:
+        - {name: workload-data, mountPath: /mounted/lumera/home}
+        - {name: workload-keyring, mountPath: /mounted/keyring/location}
+  volumes:
+    - name: workload-data
+      persistentVolumeClaim: {claimName: <same-workload-data-pvc>}
+    - name: workload-keyring
+      persistentVolumeClaim: {claimName: <same-keyring-pvc>}
+```
+
+```bash
+kubectl -n <namespace> apply -f evmigration-once.yaml
+kubectl -n <namespace> attach -it pod/evmigration-once
+kubectl -n <namespace> wait --for=jsonpath='{.status.phase}'=Succeeded pod/evmigration-once --timeout=10m
+kubectl -n <namespace> logs pod/evmigration-once > "$EVIDENCE_DIR/kubernetes-dry-run.txt"
+kubectl -n <namespace> delete pod/evmigration-once --wait=true
+```
+
+Approve the dry-run transcript, remove only the final `--dry-run` item from the reviewed YAML, and repeat `apply`/`attach`/`wait` exactly once for the live Pod. Save its logs, then delete it before restoring the StatefulSet. If the keyring is not on a dedicated PVC, reproduce the workload's exact Secret/CSI mount instead; never copy mnemonic or private-key material into a ConfigMap or command argument.
+
+For non-validator accounts, substitute the manifest-pinned `migrate-account.sh` and omit `--i-have-stopped-the-node`. Use a manifest-pinned batch/multisig entry point only when the matching method guide explicitly requires it; never improvise an unbound entry point.
+
+Do not put a mnemonic in argv. Do not use `--yes` until the reviewed dry-run transcript and destination proof are approved. Capture the tx hash/public addresses, but redact terminal output before sharing.
+
+## 7. Retry boundary: query before any retry
+
+Before broadcast, failures are reversible: fix binary/config/keyring/RPC inputs and repeat dry-run. After a tx hash is returned, or after an ambiguous timeout/connection loss during broadcast, **do not rebroadcast**. Query public state first:
+
+```bash
+"$LUMERAD" query tx <tx-hash> --node <trusted-rpc> --output json
+"$LUMERAD" query evmigration migration-record <legacy-address> \
+  --node <trusted-rpc> --output json
+```
+
+A migration record is authoritative and irreversible; finalize forward. If neither query proves inclusion, preserve the full redacted error and escalate before another broadcast. A deterministic pre-CheckTx rejection with no tx hash and no migration record may be corrected and retried.
+
+## 8. Finalize, restart, and verify
+
+Apply the account-specific local finalization described in the validator, supernode, or relayer guide. Then restart exactly one supervised instance.
+
+```bash
+# systemd
+sudo systemctl start lumerad
+sudo systemctl is-active --quiet lumerad
+sudo journalctl -u lumerad --since '10 minutes ago' --no-pager | tail -n 200
+
+# Docker alternative
+docker start <container>
+docker inspect -f '{{.State.Running}} {{.State.Status}}' <container>
+docker logs --since 10m <container> 2>&1 | tail -n 200
+
+# Kubernetes alternative
+kubectl -n <namespace> scale statefulset/<name> --replicas=<original-count>
+kubectl -n <namespace> rollout status statefulset/<name> --timeout=5m
+kubectl -n <namespace> logs statefulset/<name> --since=10m --all-containers=true | tail -n 200
+```
+
+Use public addresses for chain checks; no keyring unlock is required:
+
+```bash
+"$LUMERAD" query evmigration migration-record <legacy-address> --node <trusted-rpc> --output json
+"$LUMERAD" query bank balances <destination-address> --node <trusted-rpc> --output json
+"$LUMERAD" status --node <trusted-rpc> | jq '.sync_info | {catching_up,latest_block_height}'
+```
+
+For supernodes, use the release-matched authenticated `sncli` client. The SuperNode registers `grpc.health.v1.Health` on its authenticated transport; a generic plaintext `grpcurl` probe does not establish that transport and is not an acceptance check. `sncli` requires a TOML config even when the remote address and endpoint are overridden on the command line. Prepare it under the discovered secured operator/supernode base directory (mode `0600`) with:
+
+- `[lumera] grpc_addr` set to a trusted Lumera chain gRPC endpoint and the exact `chain_id`;
+- `[keyring] backend`, `dir`, and `key_name` set to the same post-migration keyring identity; `local_address` must equal that key's migrated address;
+- no plaintext passphrase; if needed, use a mode-`0600` `passphrase_file` supplied by the platform secret mechanism;
+- `[supernode] address` and `grpc_endpoint` set to the migrated SuperNode identity and its authenticated gRPC endpoint.
+
+This check has the same exact PR-2 compatibility dependency as destination prestaging: the manifest-pinned no-echo implementation must have placed the destination key in this keyring, and the SuperNode config must already reference that migrated identity. Otherwise stop; do not work around the gate by using unauthenticated `grpcurl` or HTTP.
+
+```bash
+umask 077
+SNCLI=/absolute/path/to/manifest-pinned/sncli
+SNCLI_CONFIG=/absolute/supernode/basedir/sncli-config.toml
+chmod 0600 "$SNCLI_CONFIG"
+# If passphrase_file is configured, its existing platform-secret mount must also be mode 0600:
+chmod 0600 /absolute/secret/mount/sncli-keyring-passphrase
+sha256sum "$SNCLI" | tee "$EVIDENCE_DIR/sncli.sha256"
+
+sudo -u <supernode-service-user> "$SNCLI" \
+  --config "$SNCLI_CONFIG" \
+  --address <migrated-supernode-lumera-address> \
+  --grpc_endpoint <supernode-grpc-host:port> \
+  health-check
+```
+
+Require exit code 0 and the exact authenticated output `✅ Health status: SERVING`. Then inspect service logs for key/backend/decode/permission failures and verify the account-specific chain record. Restore any temporary RPC timeout only after verification.
+
+## 9. Portal no-code gate (live browser evidence required)
+
+Portal source inspection is not acceptance evidence. Before release approval, attach a sanitized live-browser evidence bundle from the exact Portal build and target chain:
+
+- Portal commit/build identifier and chain profile are visible.
+- Review screen visibly shows legacy address, destination Lumera address, Ethereum hex address, and account type before signing.
+- Destination freshness succeeds; an intentionally occupied destination is blocked before signing/broadcast.
+- Validator flow visibly requires maintenance planned, node stopped, and commands copied.
+- Sign/confirm screen repeats From/To and the irreversible warning before the enabled migrate action.
+- Network trace or explorer evidence proves only one broadcast occurred.
+- Success screen shows tx hash and the on-chain migration record; refresh preserves the migrated state.
+- Failure evidence covers rejected signing, destination preflight failure, and ambiguous broadcast without leaking secrets.
+- Screenshots, HAR, and console logs are redacted: no mnemonic, private key, passphrase, auth header, cookie, bearer token, or full environment dump.
+
+The current Portal source derives and displays the destination and runs destination preflight before proof signing and again before broadcast. Therefore no fourth-PR product blocker was proven by source inspection, but the live-browser gate above remains mandatory.
+
+## 10. Compatibility manifest and owned-testnet provenance
+
+Use:
+
+- [`../operator-artifacts/compatibility-manifest.schema.json`](../operator-artifacts/compatibility-manifest.schema.json)
+- [`../operator-artifacts/compatibility-manifest.template.json`](../operator-artifacts/compatibility-manifest.template.json)
+- [`../operator-artifacts/owned-testnet-baseline.template.json`](../operator-artifacts/owned-testnet-baseline.template.json)
+
+The current release workflow publishes a SHA-256 `release_checksum` beside the tarball, and current release commits may be GitHub-signed, but neither authenticates separately downloaded release artifacts. The template therefore fails closed with `approval.status = "blocked"`.
+
+The final approved manifest is an immutable RFC 8785 JCS file. Its detached Sigstore bundle is published as `compatibility-manifest.sigstore.json`; the bundle is **not embedded back into the signed manifest**, so the process is non-circular. Before canonicalization, the release owner must supply the trusted certificate identity and OIDC issuer, record them in `approval.detached_signature`, set the final approval fields, and revalidate the completed draft. Canonicalize and sign those immutable bytes, then verify without modifying either file. Never edit approval or signature metadata after canonicalization/signing. Keyless `cosign sign-blob` is required; do not introduce a long-lived private signing secret.
+
+The schema rejects `approved` while PR-2 prestaging is blocked, any validation is not `pass`, any required binary/helper/guide identity is a placeholder or zero hash, release-owner approval is false, or trusted signer identity/issuer is missing/placeholder. Schema acceptance does not prove a signature cryptographically: approval is effective only after the exact detached verification command succeeds over the published canonical manifest bytes.
diff --git a/docs/evm-integration/user-guides/relayer-migration.md b/docs/evm-integration/user-guides/relayer-migration.md
index 0f584d78..a42f9d13 100644
--- a/docs/evm-integration/user-guides/relayer-migration.md
+++ b/docs/evm-integration/user-guides/relayer-migration.md
@@ -4,6 +4,8 @@
 **Applies to**: operators running a Hermes IBC relayer whose Lumera signing account is a legacy (coin-type 118 `secp256k1`) account, against an EVM-enabled Lumera chain (post-EVM upgrade)
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
+> **Mandatory operations gate:** Use the [EVM Migration Operator Runbook](operator-migration-runbook.md) before this relayer procedure. The runbook adds release/binary/keyring provenance, mode-0600 config backup, no-echo destination staging, verified stop/restart alternatives, a one-broadcast rule, and secret-redacted evidence; this guide remains authoritative for Hermes' pinned HD path and key replacement.
+
 ---
 
 ## Overview
@@ -76,46 +78,57 @@ Validate:
 hermes config validate    # must print: SUCCESS configuration is valid
 ```
 
-### Step 2 — Create the EVM destination key in lumerad
+### Step 2 — Pre-stage the EVM destination key in lumerad
+
+Use only the compatibility manifest's **verified, named, and hashed PR-2 no-echo implementation** to create/recover `relayer-evm` as coin type 60 / `eth_secp256k1` in the exact lumerad keyring discovered by the operator runbook. The implementation must accept a hidden TTY or protected file descriptor and must not place the mnemonic in argv, a shell variable, shell history, or logs. If that manifest dependency is blocked, stop.
 
-The migration's destination key must live in the **lumerad** keyring (alongside the legacy relayer key, so `claim-legacy-account` can sign). Create it and note its address:
+Record only the public destination address:
 
 ```bash
-lumerad keys add relayer-evm --coin-type 60 --algo eth_secp256k1 --keyring-backend test
-NEWADDR=$(lumerad keys show relayer-evm -a --keyring-backend test)
-echo "$NEWADDR"
+NEWADDR=$(sudo -u <relayer-service-user> /absolute/approved/lumerad keys show relayer-evm -a \
+  --home /absolute/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /absolute/keyring/location)
+printf '%s\n' "$NEWADDR"
 ```
 
-Capture the mnemonic printed at creation — you need it for Hermes in Step 5. (Alternatively, generate the key inside Hermes in Step 3 and recover it into lumerad; either way the same mnemonic must end up in both keyrings.)
+The destination mnemonic is transferred to Hermes only through the same protected custody channel used by PR-2. The following steps refer to a temporary operator-owned mode-`0600` file at `/run/secrets/relayer-evm.mnemonic`; never place its contents in a shell variable or shared path, and securely remove it after Step 6.
 
 ### Step 3 — GATE: prove Hermes derives the same address
 
 Before the irreversible migration, confirm Hermes derives **exactly** `$NEWADDR` from the relayer mnemonic with the pinned path:
 
 ```bash
-# pipe the mnemonic in; never write it to a shared path
-printf '%s\n' "$RELAYER_EVM_MNEMONIC" | \
-  hermes keys add --chain lumera-mainnet-1 --key-name relayer-evm-gate \
-    --mnemonic-file /dev/stdin --hd-path "m/44'/60'/0'/0/0"
-
-hermes keys list --chain lumera-mainnet-1 | grep relayer-evm-gate
+umask 077
+test "$(stat -c '%a' /run/secrets/relayer-evm.mnemonic)" = 600
+sudo -u <relayer-service-user> hermes keys add \
+  --chain lumera-mainnet-1 --key-name relayer-evm-gate \
+  --mnemonic-file /run/secrets/relayer-evm.mnemonic \
+  --hd-path "m/44'/60'/0'/0/0"
+
+sudo -u <relayer-service-user> hermes keys list --chain lumera-mainnet-1 | grep relayer-evm-gate
 # the printed address MUST equal $NEWADDR. If it does not, STOP — do not migrate.
-hermes keys delete --chain lumera-mainnet-1 --key-name relayer-evm-gate
+sudo -u <relayer-service-user> hermes keys delete --chain lumera-mainnet-1 --key-name relayer-evm-gate
 ```
 
 If the addresses differ, re-check Step 1 (`address_type`) and the `--hd-path`. **Do not proceed past this gate on a mismatch** — you would migrate funds to an account Hermes cannot sign for.
 
 ### Step 4 — Pause relaying and migrate the account
 
-Stop the relayer so it does not sign with an account that is about to be blocked, then migrate. (`migrate-account.sh` is the bundled helper — see [migration-scripts.md](migration-scripts.md). Both keys must be in the same lumerad keyring.)
+Stop and prove stopped using the relayer's actual supervisor branch in the operator runbook. Then run the manifest-pinned helper as the discovered service user, with the exact approved binary/home/backend/keyring and trusted external RPC. The successful post-stop dry-run and destination-address match are mandatory; the following live command is run once only:
 
 ```bash
-# stop the hermes process/container (resumes after Step 6)
-./scripts/migrate-account.sh relayer-legacy relayer-evm \
-  --chain-id lumera-mainnet-1 --node tcp://localhost:26657 --yes
+sudo -u <relayer-service-user> /absolute/approved/scripts/migrate-account.sh \
+  relayer-legacy relayer-evm \
+  --binary /absolute/approved/lumerad \
+  --home /absolute/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /absolute/keyring/location \
+  --chain-id lumera-mainnet-1 \
+  --node <trusted-rpc>
 ```
 
-`relayer-legacy` is the legacy relayer key in your lumerad keyring. Migration is fee-free; the full balance moves to `$NEWADDR`. Verify:
+For Docker/Kubernetes, use the runbook's one-shot container/Pod form with these account-helper arguments; do not run this host/systemd form against container storage. `relayer-legacy` is the legacy relayer key in the same lumerad keyring. Migration is fee-free; the full balance moves to `$NEWADDR`. On a tx hash or ambiguous transport failure, apply the runbook's query-before-retry rule. Verify:
 
 ```bash
 lumerad query evmigration migration-record <legacy-addr> --output json | jq '.record.new_address'  # == $NEWADDR
@@ -124,17 +137,23 @@ lumerad query bank balances "$NEWADDR" --output json | jq '.balances'
 
 ### Step 5 — Replace the Hermes relayer key with the EVM key
 
-Back up and remove the old key, then import the EVM key under the relayer's `key_name`, **with the pinned path**:
+Back up and remove the old key, then import the EVM key under the relayer's `key_name`, **with the pinned path**. Keep the backup on an encrypted operator-controlled volume, never in a shared `/tmp` path:
 
 ```bash
-cp ~/.hermes/keys/lumera-mainnet-1/keyring-test/relayer.json /tmp/relayer.json.bak
-hermes keys delete --chain lumera-mainnet-1 --key-name relayer
-
-printf '%s\n' "$RELAYER_EVM_MNEMONIC" | \
-  hermes keys add --chain lumera-mainnet-1 --key-name relayer \
-    --mnemonic-file /dev/stdin --hd-path "m/44'/60'/0'/0/0"
-
-hermes keys list --chain lumera-mainnet-1 | grep ' relayer '   # MUST show $NEWADDR
+umask 077
+RELAYER_BACKUP_DIR=/absolute/encrypted/operator-backup/relayer-$(date -u +%Y%m%dT%H%M%SZ)
+install -d -m 0700 "$RELAYER_BACKUP_DIR"
+install -m 0600 ~/.hermes/keys/lumera-mainnet-1/keyring-test/relayer.json \
+  "$RELAYER_BACKUP_DIR/relayer.json.bak"
+stat -c '%a %n' "$RELAYER_BACKUP_DIR/relayer.json.bak"  # must be 600
+
+sudo -u <relayer-service-user> hermes keys delete --chain lumera-mainnet-1 --key-name relayer
+sudo -u <relayer-service-user> hermes keys add \
+  --chain lumera-mainnet-1 --key-name relayer \
+  --mnemonic-file /run/secrets/relayer-evm.mnemonic \
+  --hd-path "m/44'/60'/0'/0/0"
+
+sudo -u <relayer-service-user> hermes keys list --chain lumera-mainnet-1 | grep ' relayer '   # MUST show $NEWADDR
 ```
 
 ### Step 6 — Restart and verify
@@ -151,10 +170,10 @@ Watch the logs for a few packets to confirm it signs and broadcasts cleanly. IBC
 
 ## Rollback / abort
 
-- **Before Step 4 (migration):** fully reversible. Restore `address_type` removal in `config.toml`, restore `relayer.json` from backup if you touched it, delete `relayer-evm*` keys. Nothing on-chain changed.
+- **Before Step 4 (migration):** fully reversible. Restore `address_type` removal in `config.toml`, restore the mode-`0600` `relayer.json` from the encrypted backup if you touched it, and delete `relayer-evm*` keys. Nothing on-chain changed.
 - **After Step 4:** the legacy address is permanently blocked; there is no rollback. The only recovery is forward — ensure Hermes holds the EVM key (Step 5) and is funded.
 
-Keep `/tmp/relayer.json.bak` only until Step 6 verifies; it is the now-blocked legacy key and a stray `.json` left in the `keyring-test/` directory can confuse Hermes' key loader — delete it once relaying is confirmed.
+Keep the encrypted `relayer.json.bak` only until Step 6 verifies; a stray `.json` left in the live `keyring-test/` directory can confuse Hermes' key loader. After relaying is confirmed, securely remove both the backup and `/run/secrets/relayer-evm.mnemonic` according to the custody platform's deletion procedure.
 
 ---
 
diff --git a/docs/evm-integration/user-guides/supernode-migration.md b/docs/evm-integration/user-guides/supernode-migration.md
index 1f191fac..f7eb5bde 100644
--- a/docs/evm-integration/user-guides/supernode-migration.md
+++ b/docs/evm-integration/user-guides/supernode-migration.md
@@ -4,6 +4,8 @@
 **Applies to**: operators running a Lumera supernode against an EVM-enabled chain (post-EVM upgrade)
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
+> **Mandatory operations gate:** Use the [EVM Migration Operator Runbook](operator-migration-runbook.md) for executable/keyring provenance, no-echo destination staging, config backup, concrete systemd/Docker/Kubernetes stop/restart evidence, the irreversible/retry boundary, and sanitized evidence requirements. This guide supplies the supernode-specific finalization steps.
+
 ---
 
 ## Overview
@@ -54,17 +56,7 @@ Before starting:
 
 ## Step 1 — Generate or recover the EVM destination key
 
-`supernode keys recover` always produces `eth_secp256k1` keys (coin-type 60). Run it with a **new key name** distinct from your legacy one:
-
-```bash
-supernode keys recover <evm-key-name> --mnemonic "twelve or twenty four mnemonic words ..."
-```
-
-Example:
-
-```bash
-`supernode keys recover supernode-evm --mnemonic "inspire words ... about"
-```
+`supernode keys recover` must produce an `eth_secp256k1` key (coin-type 60) under a **new key name** distinct from the legacy key. **Required PR-2 compatibility dependency:** use the release's approved no-echo destination-prestage operation named and hashed in the compatibility manifest. It must read the mnemonic from a hidden TTY or protected input descriptor, never from argv. PR-3 intentionally does not invent a command for an unfinished PR-2 interface. If the manifest reports this dependency as blocked, stop; do not use the legacy `--mnemonic "..."` argv form.
 
 The output prints the new EVM address derived at coin type 60 from the chosen destination mnemonic. Verify:
 
@@ -193,10 +185,9 @@ Note the `new_address` — you'll verify that it matches what the supernode deri
 
 ### Step B3 — Recover the new EVM key into the supernode keyring
 
-Exactly the same operation as Path A's Step 1. **Use the same mnemonic you used in Keplr** — this is the critical piece that makes Path B work:
+Exactly the same operation as Path A's Step 1. **Use the same mnemonic you used in Keplr** — this is the critical piece that makes Path B work. Run the release-manifest-approved PR-2 no-echo destination-prestage operation, then run:
 
 ```bash
-supernode keys recover <evm-key-name> --mnemonic "twelve or twenty four mnemonic words ..."
 supernode keys list
 ```
 
diff --git a/docs/evm-integration/user-guides/validator-migration.md b/docs/evm-integration/user-guides/validator-migration.md
index 244d147c..829e8b85 100644
--- a/docs/evm-integration/user-guides/validator-migration.md
+++ b/docs/evm-integration/user-guides/validator-migration.md
@@ -4,6 +4,8 @@
 **Applies to**: validator operators running a Lumera validator against an EVM-enabled chain (post-EVM upgrade)
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
+> **Mandatory operations gate:** Run the [EVM Migration Operator Runbook](operator-migration-runbook.md) before this validator procedure. It requires supervisor/user/base-dir/config/keyring discovery, a mode-0600 config backup, verified destination identity, proof that every instance using the consensus key is stopped, one broadcast, and public-address/gRPC/log verification.
+
 ---
 
 ## Overview
@@ -77,29 +79,24 @@ lumerad query evmigration params
 
 If `enable_migration: false`, migration is disabled chain-wide and you must wait for governance to enable it.
 
-## Step 2 — Prepare the EVM destination key
-
-```bash
-# Legacy key (coin-type 118 / secp256k1) — the one currently registered on-chain
-lumerad keys add val-legacy --recover --coin-type 118 --key-type secp256k1 --keyring-backend file
-
-# New EVM key (coin type 60 / eth_secp256k1) — generate a mnemonic
-lumerad keys add val-new --coin-type 60 --key-type eth_secp256k1 --keyring-backend file
-```
+## Step 2 — Pre-stage the EVM destination key
 
-> **Legacy key already in the keyring?** If the operator's legacy (coin-type 118) key is already present — which is the common case, since it's the key you've been running the validator with — `keys add val-legacy --recover` fails with **`duplicated address created`**. That's expected: the recovered key derives the *same* bech32 address as the one already stored, and a keyring can't hold the same address under two names. **Skip this `keys add` step and pass the existing key's name as the legacy argument** to the migration command (Step 4) or to `migrate-validator.sh`. You only need to recover the new EVM key (`val-new`).
+Use the compatibility manifest's verified, named, and hashed PR-2 no-echo destination-prestage implementation to place `val-new` in the exact validator-operator keyring discovered by the operator runbook. It must create/recover coin type 60 / `eth_secp256k1` under a new key name, accept the mnemonic only through hidden TTY or protected input descriptor, and never emit it or place it in argv. If the PR-2 dependency is blocked, stop.
 
-Alternatively, add `--recover` to derive `val-new` from an existing mnemonic, including the legacy mnemonic. Same or different mnemonics are both valid. The destination requirements are coin type `60`, key type `eth_secp256k1`, a fresh on-chain address, and control of the key.
+The legacy key is normally already present. Do not recover it again under a second name: a keyring rejects the duplicate address. Pass the existing legacy key name to the manifest-pinned helper.
 
-> **The new EVM address must be fresh — do not fund or use it before migrating.** The migration moves all balances and state to the destination atomically and **refuses to run if the destination already exists on-chain** (the chain and `migrate-validator.sh` both check this). It's tempting to send "a little gas" to the new address first; don't. If the destination already has account state, derive a different coin-type 60 key, or complete the migration first and fund it afterward. The pre-flight will surface this as a destination-freshness failure (`new address ... already exists on-chain`).
+The destination requirements are coin type `60`, key type `eth_secp256k1`, a fresh on-chain address, and proven custody. **Do not fund or use it before migrating.** The chain and helper reject a destination with existing account state.
 
-Verify both are present:
+Verify both public key records using the exact approved binary/home/backend/location:
 
 ```bash
-lumerad keys list --keyring-backend file
+sudo -u <validator-service-user> /absolute/approved/lumerad keys list \
+  --home /absolute/lumera/home \
+  --keyring-backend <backend> \
+  --keyring-dir /absolute/keyring/location
 ```
 
-You should see `val-legacy` with pubkey type `/cosmos.crypto.secp256k1.PubKey` and `val-new` with pubkey type `/cosmos.evm.crypto.v1.ethsecp256k1.PubKey`.
+You should see the existing legacy key with pubkey type `/cosmos.crypto.secp256k1.PubKey` and `val-new` with pubkey type `/cosmos.evm.crypto.v1.ethsecp256k1.PubKey`.
 
 ## Step 3 — Run the pre-flight estimate
 
@@ -189,9 +186,7 @@ If instead the validator is still `BOND_STATUS_UNBONDING` (not yet `UNBONDED`),
 
 ## Step 4 — Stop the validator
 
-```bash
-systemctl stop lumerad   # or however you supervise the node — see "Note on systemctl commands" in the Overview
-```
+Use the operator runbook's exact systemd, Docker, or Kubernetes branch to stop **and prove stopped** every instance that can access the consensus key. Record the evidence and keep container orchestrator reconciliation paused. A bare `systemctl stop` is not a valid substitute for containerized deployments.
 
 **Stopping the node before you broadcast is mandatory, not a formality.** Migration re-keys a live, bonded validator in a single transaction: it rewrites the **operator (staking) key** and the on-chain consensus-address→operator mapping. The **consensus key itself is unchanged** — and that is precisely what makes a running node dangerous here.
 
diff --git a/scripts/evmigration-common.sh b/scripts/evmigration-common.sh
index 39224984..ce00ae4c 100755
--- a/scripts/evmigration-common.sh
+++ b/scripts/evmigration-common.sh
@@ -45,6 +45,14 @@ YES=0
 DRY_RUN=0
 # shellcheck disable=SC2034
 BIN="lumerad"
+# Immutable executable identity populated once by require_binary.
+BIN_VERSION=""
+BIN_SHA256=""
+BIN_SOURCE="unresolved"
+_BINARY_RESOLVED=0
+KEYRING_BACKEND_SOURCE="unresolved"
+KEYRING_LOCATION=""
+KEYRING_LOCATION_SOURCE="unresolved"
 # shellcheck disable=SC2034
 LEGACY_KEY=""
 # shellcheck disable=SC2034
@@ -84,14 +92,18 @@ log_error() { printf '%sERROR%s %s\n' "$_C_ERR"  "$_C_RESET" "$*" >&2; }
 
 # Print a concise orientation block before work begins. Never prints secrets.
 log_run_summary() {
-  local operation="$1" mode="LIVE (will ask before broadcast)" keyring_location="default"
+  local operation="$1" mode="LIVE (will ask before broadcast)"
   (( ${DRY_RUN:-0} == 1 )) && mode="DRY RUN (no broadcast)"
-  [[ -n "${KEYRING_DIR:-}" ]] && keyring_location="$KEYRING_DIR"
   {
     printf '\n==== %s ====\n' "$operation"
     printf '  Mode:     %s\n' "$mode"
     printf '  RPC:      %s\n' "${NODE:-<not set>}"
-    printf '  Keyring:  %s (%s)\n' "${KEYRING_BACKEND:-test}" "$keyring_location"
+    printf '  Binary:          %s\n' "${BIN:-<not resolved>}"
+    printf '  Binary version:  %s\n' "${BIN_VERSION:-<not resolved>}"
+    printf '  Binary SHA-256:  %s\n' "${BIN_SHA256:-<not resolved>}"
+    printf '  Binary source:   %s\n' "${BIN_SOURCE:-unresolved}"
+    printf '  Keyring backend:  %s (%s)\n' "${KEYRING_BACKEND:-test}" "${KEYRING_BACKEND_SOURCE:-unresolved}"
+    printf '  Keyring location: %s (%s)\n' "${KEYRING_LOCATION:-<not resolved>}" "${KEYRING_LOCATION_SOURCE:-unresolved}"
     printf '  Legacy:   %s\n' "${LEGACY_KEY:-<from input file>}"
     printf '  New key:  %s\n' "${NEW_KEY:-<from input file>}"
     printf '==============================\n\n'
@@ -194,6 +206,10 @@ parse_common_flags() {
   YES=0
   DRY_RUN=0
   BIN="lumerad"
+  BIN_VERSION=""
+  BIN_SHA256=""
+  BIN_SOURCE="unresolved"
+  _BINARY_RESOLVED=0
   LEGACY_KEY=""
   NEW_KEY=""
 
@@ -238,10 +254,51 @@ require_jq() {
 }
 
 require_binary() {
-  if ! command -v "$BIN" >/dev/null 2>&1 && [[ ! -x "$BIN" ]]; then
-    log_error "lumerad binary not found: $BIN"
+  (( ${_BINARY_RESOLVED:-0} == 1 )) && return 0
+
+  local requested="$BIN" located version_output
+  if ! located=$(command -v -- "$requested" 2>/dev/null); then
+    log_error "lumerad binary not found: $requested"
+    exit 2
+  fi
+  if [[ ! -x "$located" ]]; then
+    log_error "lumerad binary is not executable: $located"
+    exit 2
+  fi
+  BIN=$(readlink -f -- "$located" 2>/dev/null || true)
+  if [[ -z "$BIN" || "$BIN" != /* || ! -x "$BIN" ]]; then
+    log_error "could not resolve lumerad to an absolute executable path: $located"
+    exit 2
+  fi
+  if [[ "$requested" == */* ]]; then
+    BIN_SOURCE="explicit --binary/path ($requested)"
+  else
+    BIN_SOURCE="PATH ($requested -> $located)"
+  fi
+
+  if ! version_output=$("$BIN" version --long 2>&1) || [[ -z "${version_output//[[:space:]]/}" ]]; then
+    log_error "could not determine lumerad version from $BIN"
+    [[ -n "$version_output" ]] && log_error "  $version_output"
+    exit 2
+  fi
+  BIN_VERSION=$(printf '%s\n' "$version_output" | sed -n 's/^[[:space:]]*version:[[:space:]]*//p' | head -n1)
+  [[ -z "$BIN_VERSION" ]] && BIN_VERSION=$(printf '%s\n' "$version_output" | sed -n '/[^[:space:]]/{p;q;}')
+  if [[ -z "$BIN_VERSION" ]]; then
+    log_error "could not determine lumerad version from $BIN"
+    exit 2
+  fi
+  if [[ -n "${LUMERA_EXPECTED_BINARY_VERSION:-}" && "$BIN_VERSION" != "$LUMERA_EXPECTED_BINARY_VERSION" ]]; then
+    log_error "lumerad version mismatch: expected $LUMERA_EXPECTED_BINARY_VERSION, got $BIN_VERSION ($BIN)"
     exit 2
   fi
+  BIN_SHA256=$(sha256sum -- "$BIN" | cut -d' ' -f1)
+  readonly BIN BIN_VERSION BIN_SHA256 BIN_SOURCE
+  _BINARY_RESOLVED=1
+  log_info "binary path: $BIN"
+  log_info "binary version: $BIN_VERSION"
+  log_info "binary SHA-256: $BIN_SHA256"
+  log_info "binary source: $BIN_SOURCE"
+
   # Entry scripts set `IFS=$'\n\t'` to harden against paths with spaces, but
   # that disables exactly the space-based word-splitting we rely on below to
   # turn each "$probe" into multiple args (e.g., "query evmigration" → two
@@ -306,13 +363,26 @@ _keyring_prompts_for_passphrase() {
 #   5. os — the Cosmos SDK default
 # Mirrors resolve_chain_id: logs the decision so the operator sees it before signing.
 resolve_keyring_backend() {
+  local default_home="${HOME:-}/.lumera"
+  if [[ -n "${KEYRING_DIR:-}" ]]; then
+    KEYRING_LOCATION="$KEYRING_DIR"
+    KEYRING_LOCATION_SOURCE="explicit --keyring-dir"
+  elif [[ -n "${HOME_DIR:-}" ]]; then
+    KEYRING_LOCATION="$HOME_DIR"
+    KEYRING_LOCATION_SOURCE="explicit --home"
+  else
+    KEYRING_LOCATION="$default_home"
+    KEYRING_LOCATION_SOURCE="SDK default home"
+  fi
   if (( KEYRING_BACKEND_EXPLICIT == 1 )); then
+    KEYRING_BACKEND_SOURCE="explicit --keyring-backend"
     log_info "keyring backend: $KEYRING_BACKEND (from --keyring-backend)"
     return 0
   fi
 
   if [[ -n "${LUMERA_KEYRING_BACKEND:-}" ]]; then
     KEYRING_BACKEND="$LUMERA_KEYRING_BACKEND"
+    KEYRING_BACKEND_SOURCE="environment LUMERA_KEYRING_BACKEND"
     log_info "keyring backend: $KEYRING_BACKEND (from \$LUMERA_KEYRING_BACKEND)"
     return 0
   fi
@@ -326,6 +396,7 @@ resolve_keyring_backend() {
         "$client_toml" | head -n1)
     if [[ -n "$v" ]]; then
       KEYRING_BACKEND="$v"
+      KEYRING_BACKEND_SOURCE="config $client_toml"
       log_info "keyring backend: $v (from $client_toml)"
       return 0
     fi
@@ -334,16 +405,19 @@ resolve_keyring_backend() {
   local kr="${KEYRING_DIR:-$home}"
   if [[ -d "$kr/keyring-test" ]]; then
     KEYRING_BACKEND="test"
+    KEYRING_BACKEND_SOURCE="detected $kr/keyring-test"
     log_info "keyring backend: test (detected keyring-test/ in $kr)"
     return 0
   fi
   if [[ -d "$kr/keyring-file" ]]; then
     KEYRING_BACKEND="file"
+    KEYRING_BACKEND_SOURCE="detected $kr/keyring-file"
     log_info "keyring backend: file (detected keyring-file/ in $kr)"
     return 0
   fi
 
   KEYRING_BACKEND="os"
+  KEYRING_BACKEND_SOURCE="SDK default"
   log_info "keyring backend: os (SDK default; no --keyring-backend, client.toml, or keyring dir found)"
 }
 
@@ -598,7 +672,9 @@ resolve_address() {
   # prompt to stderr; redirecting it made the script appear to hang while it
   # was actually waiting for input.
   if ! addr=$(lumerad_keys show "$key_name" -a); then
-    log_error "key not found in keyring: $key_name"
+    # Preserve lumerad's typed/exit diagnostic. Do not infer key absence from
+    # arbitrary stderr: decode, backend, permission, and unlock failures share
+    # the same non-zero process contract on supported CLI versions.
     exit 1
   fi
   printf '%s\n' "$addr"
diff --git a/scripts/migrate-account.sh b/scripts/migrate-account.sh
index 2b6ae314..278766a0 100755
--- a/scripts/migrate-account.sh
+++ b/scripts/migrate-account.sh
@@ -42,9 +42,9 @@ _USAGE_EXAMPLES="  # Standard migration — both keys already in the keyring:
 main() {
   parse_common_flags "$@"
   resolve_keyring_backend
+  require_binary
   log_run_summary "Lumera account migration"
   log_info "[1/7] validating local prerequisites"
-  require_binary
   require_jq
   log_info "[2/7] resolving chain ID from RPC endpoint $NODE"
   resolve_chain_id
diff --git a/scripts/migrate-validator.sh b/scripts/migrate-validator.sh
index 5626551a..e39c0dfd 100755
--- a/scripts/migrate-validator.sh
+++ b/scripts/migrate-validator.sh
@@ -55,9 +55,9 @@ main() {
 
   parse_common_flags "$@"
   resolve_keyring_backend
+  require_binary
   log_run_summary "Lumera validator migration"
   log_info "[1/7] validating local prerequisites"
-  require_binary
   require_jq
 
   log_info "[2/7] resolving chain ID from RPC endpoint $NODE"
diff --git a/tests/scripts/common.bats b/tests/scripts/common.bats
index c1ad168d..40c1f535 100644
--- a/tests/scripts/common.bats
+++ b/tests/scripts/common.bats
@@ -1013,3 +1013,124 @@ JSON
   '
   [[ "$output" != *"unlocking keyring to sign and simulate"* ]]
 }
+
+# ---- PR-3 executable and keyring provenance regressions ---------------------
+
+@test "require_binary pins a PATH symlink to one absolute canonical path with spaces" {
+  local tmp real link SHIM_BIN="$BATS_TEST_DIRNAME/fixtures/lumerad-shim.sh"
+  tmp=$(mktemp -d)
+  mkdir -p "$tmp/bin with spaces" "$tmp/path"
+  real="$tmp/bin with spaces/lumerad-real"
+  link="$tmp/path/lumerad"
+  cp "$SHIM_BIN" "$real"
+  ln -s "$real" "$link"
+  run env PATH="$tmp/path:$PATH" bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN=lumerad
+    require_binary
+    printf "BIN=%s\n" "$BIN"
+  '
+  rm -rf "$tmp"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BIN=$real"* ]]
+  [[ "$output" == *"binary source: PATH"* ]]
+}
+
+@test "require_binary honors explicit binary instead of stale PATH" {
+  local tmp approved stale SHIM_BIN="$BATS_TEST_DIRNAME/fixtures/lumerad-shim.sh"
+  tmp=$(mktemp -d)
+  mkdir -p "$tmp/approved dir" "$tmp/stale"
+  approved="$tmp/approved dir/lumerad"
+  stale="$tmp/stale/lumerad"
+  cp "$SHIM_BIN" "$approved"
+  cp "$SHIM_BIN" "$stale"
+  run env PATH="$tmp/stale:$PATH" SHIM_VERSION=v1.20.1 APPROVED="$approved" bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN="$APPROVED"
+    require_binary
+    printf "BIN=%s VERSION=%s\n" "$BIN" "$BIN_VERSION"
+  '
+  rm -rf "$tmp"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BIN=$approved VERSION=v1.20.1"* ]]
+  [[ "$output" != *"$stale"* ]]
+}
+
+@test "require_binary rejects an approved-version mismatch" {
+  setup_shim
+  run env SHIM_VERSION=v1.6.1 LUMERA_EXPECTED_BINARY_VERSION=v1.20.1 bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN='"$SHIM_BIN"'
+    require_binary
+  '
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"version mismatch"*"expected v1.20.1"*"got v1.6.1"* ]]
+}
+
+@test "require_binary rejects unknown version output" {
+  local tmp
+  tmp=$(mktemp -d)
+  printf '%s\n' '#!/usr/bin/env bash' 'case "$*" in "version --long") exit 0 ;; *"--help") exit 0 ;; esac' >"$tmp/lumerad"
+  chmod +x "$tmp/lumerad"
+  run bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN='"$tmp"'/lumerad
+    require_binary
+  '
+  rm -rf "$tmp"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"could not determine lumerad version"* ]]
+}
+
+@test "resolve_address preserves backend failure without relabeling" {
+  setup_shim
+  run env SHIM_KEYS_ERROR="failed to decrypt keyring: permission denied" bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN='"$SHIM_BIN"'; KEYRING_BACKEND=test
+    resolve_address private-key-name
+  '
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"failed to decrypt keyring: permission denied"* ]]
+  [[ "$output" != *"key not found in keyring"* ]]
+}
+
+@test "resolve_address preserves malformed key decode failure without relabeling" {
+  setup_shim
+  run env SHIM_KEYS_ERROR="failed to decode keyring record: malformed armor" bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN='"$SHIM_BIN"'; KEYRING_BACKEND=test
+    resolve_address malformed-key
+  '
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"failed to decode keyring record: malformed armor"* ]]
+  [[ "$output" != *"key not found in keyring"* ]]
+}
+
+@test "resolve_address preserves CLI key absence contract" {
+  setup_shim
+  run env SHIM_KEYS_MISSING=absent bash -c '
+    source '"$SCRIPTS_DIR"'/evmigration-common.sh
+    BIN='"$SHIM_BIN"'; KEYRING_BACKEND=test
+    resolve_address absent
+  '
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"key not found: absent"* ]]
+  [[ "$output" != *"key not found in keyring"* ]]
+}
+
+@test "keyring backend and location provenance render separately" {
+  local home kr
+  home=$(mktemp -d); kr=$(mktemp -d)
+  KEYRING_BACKEND=test
+  KEYRING_BACKEND_EXPLICIT=1
+  HOME_DIR="$home"
+  KEYRING_DIR="$kr"
+  DRY_RUN=1 NODE=tcp://local:1 LEGACY_KEY=legacy NEW_KEY=new
+  resolve_keyring_backend
+  run log_run_summary "test migration"
+  rm -rf "$home" "$kr"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Keyring backend:  test (explicit --keyring-backend)"* ]]
+  [[ "$output" == *"Keyring location: $kr (explicit --keyring-dir)"* ]]
+  [[ "$output" != *"test (default)"* ]]
+}
diff --git a/tests/scripts/fixtures/lumerad-shim.sh b/tests/scripts/fixtures/lumerad-shim.sh
index b5addd57..c3193f19 100755
--- a/tests/scripts/fixtures/lumerad-shim.sh
+++ b/tests/scripts/fixtures/lumerad-shim.sh
@@ -6,6 +6,8 @@
 #   SHIM_COMBINE_EXIT=<n> force exit code for tx evmigration combine-proof only
 #   SHIM_FIXTURE=<name>   force a specific fixture name (without .json)
 #   SHIM_STDERR=<msg>     emit this to stderr before exiting
+#   SHIM_VERSION=<value>  version reported by `version --long`
+#   SHIM_KEYS_ERROR=<msg> make `keys show` fail with this exact diagnostic
 #
 # Per-command overrides let a single test change just one endpoint:
 #   SHIM_ESTIMATE_FIXTURE, SHIM_RECORD_FIXTURE, SHIM_PARAMS_FIXTURE,
@@ -100,6 +102,7 @@ fi
 # Route on argv. Per-command env vars let a single test override just one
 # endpoint without affecting the others.
 case "$*" in
+  "version --long")                                          printf 'version: %s\n' "${SHIM_VERSION:-v1.20.1-test}" ;;
   "query evmigration migration-estimate "*)               emit "${SHIM_ESTIMATE_FIXTURE:-estimate-ok}" ;;
   "query evmigration migration-record "*)
     if [[ -n "${SHIM_STATE_FILE:-}" && -f "$(pending_file)" ]]; then
@@ -163,6 +166,10 @@ case "$*" in
     emit "${SHIM_TX_FIXTURE:-tx-success}"
     ;;
   "keys show "*)
+    if [[ -n "${SHIM_KEYS_ERROR:-}" ]]; then
+      printf '%s\n' "$SHIM_KEYS_ERROR" >&2
+      exit "${SHIM_KEYS_EXIT:-1}"
+    fi
     # Route on the key name (second word after "show") and presence of --output json.
     # If --output json: emit a keys-show-<name>.json fixture; fall back to a generic one.
     # If -a (or default): emit the stub address like before.
diff --git a/tests/scripts/migrate-account.bats b/tests/scripts/migrate-account.bats
index 44e63881..23bb28a0 100644
--- a/tests/scripts/migrate-account.bats
+++ b/tests/scripts/migrate-account.bats
@@ -58,3 +58,44 @@ setup() {
   [ "$status" -eq 0 ]
   [[ "$output" == *"migration complete"* ]]
 }
+
+@test "migrate-account.sh executes the explicit canonical binary and reports provenance" {
+  local tmp real link keyring_dir
+  tmp=$(mktemp -d)
+  mkdir -p "$tmp/bin with spaces" "$tmp/approved" "$tmp/keyring location"
+  real="$tmp/bin with spaces/lumerad-real"
+  link="$tmp/approved/lumerad"
+  keyring_dir="$tmp/keyring location"
+  printf '#!/usr/bin/env bash\nexec %q "$@"\n' "$SHIM" >"$real"
+  chmod +x "$real"
+  ln -s "$real" "$link"
+
+  run env SHIM_VERSION=v1.20.1-operator-test \
+    "$SCRIPTS_DIR/migrate-account.sh" \
+    --binary "$link" \
+    --chain-id shim-test \
+    --keyring-backend test \
+    --keyring-dir "$keyring_dir" \
+    --dry-run --yes \
+    legacykey newkey
+
+  rm -rf "$tmp"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Binary:          $real"* ]]
+  [[ "$output" == *"Binary version:  v1.20.1-operator-test"* ]]
+  [[ "$output" == *"Binary source:   explicit --binary/path ($link)"* ]]
+  [[ "$output" == *"Keyring backend:  test (explicit --keyring-backend)"* ]]
+  [[ "$output" == *"Keyring location: $keyring_dir (explicit --keyring-dir)"* ]]
+  [[ "$output" == *"Migration preview"* ]]
+}
+
+@test "migrate-account.sh preserves a keyring permission failure end to end" {
+  run env SHIM_KEYS_ERROR="failed to decrypt keyring: permission denied" \
+    "$SCRIPTS_DIR/migrate-account.sh" \
+    --binary "$SHIM" --chain-id shim-test --keyring-backend test \
+    --dry-run --yes legacykey newkey
+
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"failed to decrypt keyring: permission denied"* ]]
+  [[ "$output" != *"key not found in keyring"* ]]
+}
diff --git a/tests/scripts/migrate-batch.bats b/tests/scripts/migrate-batch.bats
index 9d30a65c..ffabea43 100644
--- a/tests/scripts/migrate-batch.bats
+++ b/tests/scripts/migrate-batch.bats
@@ -119,6 +119,11 @@ if [[ "$*" == *"--help"* ]]; then
   exit 0
 fi
 
+if [[ "$*" == "version --long" ]]; then
+  printf 'version: v1.20.1-test\n'
+  exit 0
+fi
+
 if [[ "${1-}" == "query" && "${2-}" == "evmigration" && "${3-}" == "migration-record" ]]; then
   exit 1
 fi

From dbec100e7a1dfff4239b7148cd180282131741b3 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 04:06:44 +0000
Subject: [PATCH 02/11] docs(evmigration): close final operator review blockers

---
 .../compatibility-manifest.schema.json        |  26 +-
 .../compatibility-manifest.template.json      |  16 +-
 .../user-guides/operator-migration-runbook.md |  59 ++---
 .../user-guides/supernode-migration.md        | 179 +++----------
 .../user-guides/validator-migration.md        | 240 ++++--------------
 5 files changed, 155 insertions(+), 365 deletions(-)

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
index bcc6da0a..d6c9fc78 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -40,10 +40,12 @@
     "artifacts": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["chain_executable", "supernode_executable", "bound_files"],
+      "required": ["chain_executable", "supernode_executable", "sncli_executable", "container_image", "bound_files"],
       "properties": {
         "chain_executable": { "$ref": "#/$defs/executable" },
         "supernode_executable": { "$ref": "#/$defs/executable" },
+        "sncli_executable": { "$ref": "#/$defs/executable" },
+        "container_image": { "$ref": "#/$defs/container_image" },
         "bound_files": {
           "type": "object",
           "additionalProperties": false,
@@ -213,7 +215,7 @@
     "non_placeholder": {
       "type": "string",
       "minLength": 3,
-      "pattern": "^(?!REPLACE(?:_|$))(?!.*<[^>]+>)(?!PLACEHOLDER$)(?!TBD$)(?!TODO$)(?!UNKNOWN$).+\\S$"
+      "pattern": "^(?!.*(?:[Pp][Ll][Aa][Cc][Ee][Hh][Oo][Ll][Dd][Ee][Rr]|[Tt][Oo][Dd][Oo]|[Tt][Bb][Dd]|[Uu][Nn][Kk][Nn][Oo][Ww][Nn]|[Rr][Ee][Pp][Ll][Aa][Cc][Ee])(?:[^A-Za-z]|$))(?!.*<[^>]+>).+\\S$"
     },
     "sha256": {
       "type": "string",
@@ -265,6 +267,24 @@
         "source": { "$ref": "#/$defs/non_placeholder" }
       }
     },
+    "container_image": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifact", "digest", "source"],
+      "properties": {
+        "artifact": { "type": "string", "minLength": 1 },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "approved_container_image": {
+      "type": "object",
+      "properties": {
+        "artifact": { "$ref": "#/$defs/non_placeholder" },
+        "digest": { "type": "string", "pattern": "^sha256:(?!0{64}$)[0-9a-f]{64}$" },
+        "source": { "$ref": "#/$defs/non_placeholder" }
+      }
+    },
     "pr2_implementation": {
       "type": "object",
       "additionalProperties": false,
@@ -320,6 +340,8 @@
       "properties": {
         "chain_executable": { "$ref": "#/$defs/approved_executable" },
         "supernode_executable": { "$ref": "#/$defs/approved_executable" },
+        "sncli_executable": { "$ref": "#/$defs/approved_executable" },
+        "container_image": { "$ref": "#/$defs/approved_container_image" },
         "bound_files": {
           "properties": {
             "scripts/evmigration-common.sh": { "$ref": "#/$defs/approved_file" },
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
index 5cdbf69d..cd2066b4 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -30,6 +30,20 @@
       "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
       "source": "REPLACE_WITH_SUPERNODE_RELEASE_ASSET_URL"
     },
+    "sncli_executable": {
+      "name": "sncli",
+      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_SNCLI",
+      "version": "REPLACE_WITH_SNCLI_VERSION",
+      "tag": "REPLACE_WITH_SNCLI_RELEASE_TAG",
+      "commit": "0000000000000000000000000000000000000000",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "source": "REPLACE_WITH_SNCLI_RELEASE_ASSET_URL"
+    },
+    "container_image": {
+      "artifact": "REPLACE_WITH_CONTAINER_IMAGE_REPOSITORY_AND_TAG",
+      "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "source": "REPLACE_WITH_CONTAINER_IMAGE_REGISTRY_URL"
+    },
     "bound_files": {
       "scripts/evmigration-common.sh": {
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
@@ -137,7 +151,7 @@
   },
   "_verification": [
     "Release owner: replace every REPLACE_WITH value and every all-zero commit/hash; approval.status=approved is schema-invalid while any remain.",
-    "Extract each release asset into a new mode-0700 directory. Verify the chain and SuperNode executable tag, commit, version, source, and SHA-256, then verify every artifacts.bound_files entry individually with sha256sum.",
+    "Extract each release asset into a new mode-0700 directory. Verify the chain, SuperNode, and sncli executable release path, tag, commit, version, source, and SHA-256; verify the container image artifact, registry source, and immutable digest; then verify every artifacts.bound_files entry individually with sha256sum.",
     "Require operator_contracts.destination_prestage_no_echo.status=verified and bind its implementation name, tag, commit, SHA-256, source, and exact no-echo contract. Do not approve an unfinished or narrative-only PR-2 dependency.",
     "Run every validation command and attach sanitized evidence. Every validation status, including owned_testnet and portal_live, must be pass before approval is schema-valid.",
     "Validate the schema under draft 2020-12, validate this manifest against it, and confirm a copy changed to approval.status=approved while retaining any blocked/postponed/placeholder field is rejected.",
diff --git a/docs/evm-integration/user-guides/operator-migration-runbook.md b/docs/evm-integration/user-guides/operator-migration-runbook.md
index fa015a65..878cbdc9 100644
--- a/docs/evm-integration/user-guides/operator-migration-runbook.md
+++ b/docs/evm-integration/user-guides/operator-migration-runbook.md
@@ -51,7 +51,7 @@ Identify `runAsUser`, command/args, PVC/config/secret mounts, base directory, an
 
 ## 2. Pin binary, home, and keyring provenance
 
-Use the exact release executable and explicit flags. The helpers resolve `--binary` once to an absolute canonical path, then print that path, the actual `version --long` version, SHA-256, and source before doing key work. They print keyring backend and keyring location separately, with each source.
+Use the exact release executables and explicit flags. The helpers resolve `--binary` once to an absolute canonical path, then print that path, the actual `version --long` version, SHA-256, and source before doing key work. They print keyring backend and keyring location separately, with each source. Independently verify all three executable records in the manifest: `artifacts.chain_executable`, `artifacts.supernode_executable`, and `artifacts.sncli_executable`, including each exact `release_path`, version, tag, commit, SHA-256, and source. For container procedures, also pull and inspect the exact `artifacts.container_image.artifact@artifacts.container_image.digest` from `artifacts.container_image.source`; a mutable tag alone is not approved.
 
 ```bash
 LUMERAD=/absolute/path/to/approved/lumerad
@@ -161,40 +161,37 @@ sudo -u <service-user> ./scripts/migrate-validator.sh \
 
 ### Docker one-shot container
 
-Do not apply the systemd command to a container deployment. Keep the original workload container stopped and run a one-shot container from the **manifest-pinned image digest**, as the same numeric UID/GID, with the stopped container's volumes. The image must contain the manifest-pinned helper and binary at the paths below; verify both hashes before use.
+Do not apply the systemd command to a container deployment. Keep the original workload container stopped and run a one-shot container from the manifest's exact `artifacts.container_image.artifact@artifacts.container_image.digest`, as the same numeric UID/GID, with the stopped container's volumes. `--volumes-from` preserves every original mount destination; it does not remap mounts. Therefore set `CONTAINER_HOME` and `CONTAINER_KEYRING_DIR` to the exact original **in-container destination paths** recorded by `docker inspect`, not invented `/mounted/...` paths. The image must contain `artifacts.bound_files["scripts/migrate-validator.sh"]` and `artifacts.chain_executable` at their manifest-pinned `release_path` values; verify both hashes before use.
 
 ```bash
-# The workload container remains stopped for both commands.
+# The workload container remains stopped for both invocations.
 test "$(docker inspect -f '{{.State.Running}}' <stopped-container>)" = false
-APPROVED_IMAGE='<registry>/<image>@sha256:<manifest-image-digest>'
+APPROVED_IMAGE='<artifacts.container_image.artifact>@<artifacts.container_image.digest>'
 SERVICE_UID_GID='<uid>:<gid>'
-
-docker run --rm -it --name evmigration-dry-run \
-  --user "$SERVICE_UID_GID" --network host \
-  --volumes-from <stopped-container>:rw \
-  --entrypoint /release/scripts/migrate-validator.sh \
-  "$APPROVED_IMAGE" \
-  <legacy-key-name> <destination-key-name> \
-  --binary /release/bin/lumerad \
-  --home /mounted/lumera/home \
-  --keyring-backend <backend> \
-  --keyring-dir /mounted/keyring/location \
-  --chain-id <chain-id> --node <trusted-rpc> \
-  --i-have-stopped-the-node --dry-run
-
-# After approving the dry-run transcript, run this live command ONCE.
-docker run --rm -it --name evmigration-live \
-  --user "$SERVICE_UID_GID" --network host \
-  --volumes-from <stopped-container>:rw \
-  --entrypoint /release/scripts/migrate-validator.sh \
-  "$APPROVED_IMAGE" \
-  <legacy-key-name> <destination-key-name> \
-  --binary /release/bin/lumerad \
-  --home /mounted/lumera/home \
-  --keyring-backend <backend> \
-  --keyring-dir /mounted/keyring/location \
-  --chain-id <chain-id> --node <trusted-rpc> \
-  --i-have-stopped-the-node
+MIGRATION_HELPER='<manifest-pinned-helper-release_path-in-image>'
+LUMERAD_IN_IMAGE='<artifacts.chain_executable.release_path-in-image>'
+CONTAINER_HOME='<original-home-mount-destination-from-docker-inspect>'
+CONTAINER_KEYRING_DIR='<original-keyring-mount-destination-from-docker-inspect>'
+
+run_migration() {
+  docker run --rm -it --name evmigration-once \
+    --user "$SERVICE_UID_GID" --network host \
+    --volumes-from <stopped-container>:rw \
+    --entrypoint "$MIGRATION_HELPER" \
+    "$APPROVED_IMAGE" \
+    <legacy-key-name> <destination-key-name> \
+    --binary "$LUMERAD_IN_IMAGE" \
+    --home "$CONTAINER_HOME" \
+    --keyring-backend <backend> \
+    --keyring-dir "$CONTAINER_KEYRING_DIR" \
+    --chain-id <chain-id> --node <trusted-rpc> \
+    --i-have-stopped-the-node "$@"
+}
+
+# These invoke the exact same reviewed command; only --dry-run differs.
+run_migration --dry-run
+# After approving the dry-run transcript, invoke the live command ONCE.
+run_migration
 ```
 
 `--network host` is an explicit example for a trusted operator-controlled host. If policy forbids it, attach the one-shot container to an approved network that can reach `<trusted-rpc>`; do not target the stopped container or an untrusted public endpoint.
diff --git a/docs/evm-integration/user-guides/supernode-migration.md b/docs/evm-integration/user-guides/supernode-migration.md
index f7eb5bde..8efbcdda 100644
--- a/docs/evm-integration/user-guides/supernode-migration.md
+++ b/docs/evm-integration/user-guides/supernode-migration.md
@@ -5,6 +5,17 @@
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
 > **Mandatory operations gate:** Use the [EVM Migration Operator Runbook](operator-migration-runbook.md) for executable/keyring provenance, no-echo destination staging, config backup, concrete systemd/Docker/Kubernetes stop/restart evidence, the irreversible/retry boundary, and sanitized evidence requirements. This guide supplies the supernode-specific finalization steps.
+>
+> **Command context used below:** populate these values from the approved manifest and runbook discovery before any chain query. `LUMERAD` must be the exact absolute `artifacts.chain_executable.release_path`. Each explicit query below receives the supported home, keyring, chain, and node flags; keys commands receive only home and keyring flags. Do not use a universal wrapper. SuperNode and `sncli` operations must likewise use the independently pinned `artifacts.supernode_executable` and `artifacts.sncli_executable` records, never PATH lookup.
+>
+> ```bash
+> LUMERAD=/absolute/path/from/approved/artifacts.chain_executable.release_path
+> LUMERA_HOME=/absolute/discovered/lumera/home
+> KEYRING_BACKEND=<test|file|os>
+> KEYRING_DIR=/absolute/discovered/keyring/location
+> CHAIN_ID=<approved-chain-id>
+> TRUSTED_RPC=<trusted-rpc>
+> ```
 
 ---
 
@@ -29,14 +40,7 @@ Both paths land in the same final state (new EVM key registered as supernode, le
 
 Path B is useful when you want to use Keplr's UX to see each step (the Portal shows balances, delegations, and a pre-migration checklist), when you need to migrate the account's balance urgently for non-supernode reasons, or when your node ops team and your wallet custody team are different people.
 
-> **Terminal alternative for Path B.** If you prefer to stay in a shell rather than use Keplr, you can drive the account-level migration with the bundled shell helper scripts instead of the Portal — the end state (on-chain migration record + matching local key) is identical, and the supernode daemon's `alreadyMigrated` branch activates the same way on restart. See [migration-scripts.md](migration-scripts.md) for the full walkthrough, including multisig rejection, pre-flight estimates, and exit codes. In short:
->
-> ```bash
-> ./scripts/migrate-account.sh legacy-key new-key \
->   --chain-id lumera-mainnet-1 --node tcp://rpc.lumera:26657
-> ```
->
-> Then continue with Step B3 (recover the new EVM key into the supernode keyring) onward.
+> **Terminal alternative for Path B.** Do not use a shortened helper command from this guide. Follow the [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once) non-validator branch with the manifest-pinned absolute `migrate-account.sh` and `lumerad` paths, discovered service identity, explicit home/keyring backend/keyring location/chain ID/trusted node, and the approved dry-run-before-live sequence. Then continue with Step B3 onward.
 
 **Why both paths work deterministically**: `supernode keys recover` derives keys at HD path `m/44'/60'/0'/0/0` using `eth_secp256k1`. Keplr uses the identical derivation for Lumera's EVM chain definition. Import the chosen destination mnemonic into both tools so they produce the same destination address. That mnemonic may be the legacy mnemonic or a different one.
 
@@ -58,13 +62,7 @@ Before starting:
 
 `supernode keys recover` must produce an `eth_secp256k1` key (coin-type 60) under a **new key name** distinct from the legacy key. **Required PR-2 compatibility dependency:** use the release's approved no-echo destination-prestage operation named and hashed in the compatibility manifest. It must read the mnemonic from a hidden TTY or protected input descriptor, never from argv. PR-3 intentionally does not invent a command for an unfinished PR-2 interface. If the manifest reports this dependency as blocked, stop; do not use the legacy `--mnemonic "..."` argv form.
 
-The output prints the new EVM address derived at coin type 60 from the chosen destination mnemonic. Verify:
-
-```bash
-supernode keys list
-```
-
-You should see both your legacy key and the newly recovered EVM key. They may use the same mnemonic or different mnemonics; the new key uses coin type `60` and `eth_secp256k1`.
+The approved pre-stage operation prints the new EVM address. Verify the resulting public key record using the manifest-pinned absolute `artifacts.supernode_executable.release_path`, the discovered SuperNode service identity/base directory, and the exact keyring backend/location from the operator runbook. Do not copy a bare `supernode keys list` shortcut that falls back to the interactive user's config or keyring.
 
 ## Step 2 — Add `evm_key_name` to `config.yml`
 
@@ -124,7 +122,7 @@ If the logs show `migration record exists on-chain but new address mismatch`, th
 Query the on-chain migration record:
 
 ```bash
-lumerad query evmigration migration-record <legacy-address>
+sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-address>
 ```
 
 The response should show `new_address` matching your EVM key's address. Also confirm the supernode's on-chain registration points at the new address:
@@ -132,8 +130,8 @@ The response should show `new_address` matching your EVM key's address. Also con
 ```bash
 # get-supernode takes the VALOPER address (lumeravaloper1…), not the account
 # address. Convert your new account address with:
-#   lumerad keys show <new-key> -a --bech val
-lumerad query supernode get-supernode <new-valoper-address>
+#   sudo -u <supernode-service-user> "$LUMERAD" keys --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" show <new-key> -a --bech val
+sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" supernode get-supernode <new-valoper-address>
 ```
 
 Finally, confirm `config.yml` reflects the switch:
@@ -178,20 +176,14 @@ Quick summary of what you'll do:
 After the Portal shows success, verify the on-chain record on the host (or on the Portal's success screen):
 
 ```bash
-lumerad query evmigration migration-record <legacy-address>
+sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-address>
 ```
 
 Note the `new_address` — you'll verify that it matches what the supernode derives locally in Step B5.
 
 ### Step B3 — Recover the new EVM key into the supernode keyring
 
-Exactly the same operation as Path A's Step 1. **Use the same mnemonic you used in Keplr** — this is the critical piece that makes Path B work. Run the release-manifest-approved PR-2 no-echo destination-prestage operation, then run:
-
-```bash
-supernode keys list
-```
-
-Confirm the printed EVM address matches the `new_address` you saw in the Portal and in the migration record. If they don't match, stop — you're using a different mnemonic than Keplr did, and the supernode will refuse to finalize.
+Exactly the same operation as Path A's Step 1. **Use the same mnemonic you used in Keplr** — this is the critical piece that makes Path B work. Run the release-manifest-approved PR-2 no-echo destination-prestage operation, then verify the public record through the same manifest-pinned absolute SuperNode executable, service identity/base directory, and explicit keyring context required there; do not use a bare key-list shortcut.
 
 ### Step B4 — Add `evm_key_name` to `config.yml`
 
@@ -290,41 +282,7 @@ The new operator account is **also** a K-of-N multisig, constructed from `eth_se
 
 ### Why automatic migration is refused
 
-The supernode daemon holds a single signing key and cannot run the K-of-N ceremony required for multisig migration. When it detects `is_multisig=true` from `MigrationEstimate`, it fatals with:
-
-```text
-legacy supernode account lumera1... is a 2-of-3 multisig; automatic migration is not supported.
-
-The daemon holds a single key and cannot run the multi-party signing ceremony.
-Please complete migration offline using the lumerad CLI, then restart supernode —
-the existing on-chain record will trigger local cleanup automatically.
-
-Four-step offline ceremony:
-
-  # 1) Each co-signer generates a fresh eth_secp256k1 sub-key; coordinator
-  #    derives the new multisig:
-  lumerad keys add <op>-eth-<N> --key-type eth_secp256k1 --keyring-backend <backend>
-  lumerad keys add <op>-msig-new --multisig <op>-eth-1,<op>-eth-2,<op>-eth-3 \
-    --multisig-threshold K --nosort --keyring-backend <backend>
-
-  # 2) Coordinator builds the proof template:
-  lumerad tx evmigration generate-proof-payload \
-    --legacy <multisig-legacy-address> \
-    --new <new-multisig-address> \
-    --new-sub-pub-keys <op>-eth-1,<op>-eth-2,<op>-eth-3 \
-    --new-threshold K \
-    --kind claim --chain-id <chain-id> --out proof.json
-
-  # 3) Each of K co-signers signs both sides in one call:
-  lumerad tx evmigration sign-proof proof.json \
-    --from <my-legacy-sub-key> --new-key <my-eth-sub-key> \
-    --keyring-backend <backend> --chain-id <chain-id> \
-    --out <signer>-partial.json
-
-  # 4) Combine and submit (no --from on submit-proof):
-  lumerad tx evmigration combine-proof *-partial.json --out tx.json
-  lumerad tx evmigration submit-proof tx.json --chain-id <chain-id>
-```
+The daemon's refusal directs operators to the offline multisig ceremony. That diagnostic is not an approved command source: do not copy any abbreviated command embedded in daemon output. Use the release manifest and [Operator Runbook](operator-migration-runbook.md) to pin the exact absolute `lumerad` path and every home/keyring/chain/node input, then follow the proof semantics below without bypassing that execution context.
 
 ### Multisig flow overview
 
@@ -332,25 +290,9 @@ You complete the 4-step offline ceremony with `lumerad`, then restart the supern
 
 #### Step 1 — Generate N fresh `eth_secp256k1` sub-keys and derive the new multisig
 
-Each co-signer generates their own destination-side eth sub-key on their own host (or wherever they hold the legacy sub-key). The coordinator collects the resulting pubkeys and derives the new multisig address:
+Each co-signer generates a destination-side eth sub-key in the exact keyring established by the operator runbook. The coordinator collects the N public keys and derives the destination composite with the same K, N, and member order as the legacy multisig. Use the manifest-pinned absolute `lumerad` path and explicit home, keyring backend, and keyring location for every key operation; do not use a bare `lumerad keys` shortcut.
 
-```bash
-# Each co-signer, on their own machine:
-lumerad keys add <op-name>-eth-<N> --key-type eth_secp256k1 \
-  --keyring-backend <backend>
-
-# Coordinator, once all N eth sub-keys are available:
-lumerad keys add <op-name>-msig-new \
-  --multisig <op-name>-eth-1,<op-name>-eth-2,<op-name>-eth-3 \
-  --multisig-threshold 2 \
-  --nosort \
-  --keyring-backend <backend>
-
-lumerad keys show <op-name>-msig-new --address
-# lumera1...   <-- the new multisig bech32; record this as new_address
-```
-
-> **`--nosort` is required, and member order must mirror the legacy side.** Without `--nosort`, `keys add` sorts sub-keys by address, so this composite address won't match the one `generate-proof-payload` derives from `--new-sub-pub-keys` (which preserves the listed order), and the signer indices won't line up. List the members in the **same order as the legacy multisig's `public_keys`** (`lumerad query auth account <multisig-legacy-address>`) so each co-signer holds the same signer index on both sides — the consensus mirror-source rule requires `legacy_proof.signer_indices == new_proof.signer_indices`.
+> **`--nosort` is required, and member order must mirror the legacy side.** The coordinator must inspect the legacy multisig through the same manifest-pinned binary and trusted node, then list destination members in that exact order so signer indices match on both sides.
 
 This replaces the old single-EOA "recover the new EVM key" step: the destination is a multisig derived from fresh eth sub-keys, not an EOA recovered from a mnemonic.
 
@@ -358,75 +300,32 @@ Set `evm_key_name` in the supernode's `config.yml` to the name of the new multis
 
 #### Step 2 — Ensure the multisig's pubkey is on-chain
 
-If the multisig has received funds but never signed a transaction, its `LegacyAminoPubKey` is nil on-chain and `generate-proof-payload` will fail. Submit any transaction from the multisig first (a 1-`ulume` self-send is sufficient), then confirm:
-
-```bash
-lumerad query auth account <multisig-legacy-address>
-```
-
-The response must show a `multisig` pubkey structure listing all N legacy sub-keys.
+If the multisig has received funds but never signed a transaction, its `LegacyAminoPubKey` is nil on-chain and proof generation fails. Complete the required pubkey-registration transaction through the runbook's manifest-pinned execution context, then query the account with the same absolute binary, explicit home/keyring context, chain ID, and trusted node. The response must show all N legacy sub-keys.
 
 #### Step 3 — Coordinator generates the proof payload template
 
-```bash
-lumerad tx evmigration generate-proof-payload \
-  --legacy <multisig-legacy-address> \
-  --new <new-multisig-address-from-step-1> \
-  --new-sub-pub-keys <op-name>-eth-1,<op-name>-eth-2,<op-name>-eth-3 \
-  --new-threshold 2 \
-  --kind claim \
-  --chain-id <chain-id> \
-  --keyring-backend <backend> \
-  --out proof.json
-```
+The coordinator generates `proof.json` with the manifest-pinned absolute chain executable, explicit home/keyring backend/keyring location, exact chain ID, trusted node, legacy address, destination public keys in legacy order, matching threshold, and `claim` proof kind. Do not copy an abbreviated proof-generation command from this guide.
 
-- `--new-sub-pub-keys` accepts either keyring key names or base64 compressed 33-byte `eth_secp256k1` pubkeys. Mix freely.
-- `--new-threshold` is **required** whenever `--new-sub-pub-keys` is set.
-- `--kind claim` targets `MsgClaimLegacyAccount`; use `--kind validator` if the multisig is also a validator operator.
-- `--chain-id` is **required** — it is embedded in the signed payload, so an empty or wrong value makes every sub-signature fail verification on-chain.
-- `generate-proof-payload` does not broadcast anything, but it **does** need keyring access (to resolve `--new-sub-pub-keys` / `--legacy-key` entries that are local key names). Pass `--keyring-backend` (and `--keyring-dir` / `--home` when applicable).
+- Destination sub-public-keys may be key names in that explicit keyring or base64 compressed 33-byte `eth_secp256k1` public keys.
+- The destination threshold is required and must match the legacy K.
+- Use `claim` for `MsgClaimLegacyAccount`; a validator operator must instead follow the validator guide.
+- The exact chain ID is embedded in every signature.
 
-Distribute `proof.json` to all co-signers.
+Distribute the resulting `proof.json` to all co-signers through the approved custody channel.
 
 #### Step 4 — Each co-signer signs both sides in one invocation
 
-Every participating co-signer must hold **both** their legacy Cosmos sub-key (`--from`) **and** their destination-side eth sub-key (`--new-key`) in the same keyring. `sign-proof` signs both sides and writes a single partial file:
-
-```bash
-lumerad tx evmigration sign-proof proof.json \
-  --from <my-legacy-sub-key-name> \
-  --new-key <my-eth-sub-key-name> \
-  --keyring-backend <backend> \
-  --chain-id <chain-id> \
-  --out <signer>-partial.json
-```
-
-`sign-proof` is idempotent on both sides — re-running it replaces this signer's prior entries in both `partial_legacy_signatures` and `partial_new_signatures`, never duplicates. Each co-signer sends their partial file back to the coordinator.
+Every participating co-signer must hold both their legacy Cosmos sub-key and destination-side eth sub-key at matching indices. Each signs both sides with the manifest-pinned absolute chain executable, their explicit home/keyring backend/keyring location, the same chain ID and trusted node, and a distinct partial-output path. Do not use a bare `sign-proof` example that can silently select another keyring. Re-signing replaces that participant's prior entries rather than duplicating them; return partials through the approved custody channel.
 
 #### Step 5 — Coordinator combines partials
 
-```bash
-lumerad tx evmigration combine-proof \
-  alice-partial.json bob-partial.json carol-partial.json \
-  --out tx.json
-```
+The coordinator combines the reviewed partial files with the same manifest-pinned absolute executable and explicit home/keyring/chain/node context, writing a single `tx.json`. Do not use an abbreviated combine command from this guide.
 
 `combine-proof` rejects the set if any two partials disagree on `chain_id`, `evm_chain_id`, `legacy_address`, `new_address`, `payload_hex`, proof kind, or either side's `sub_pub_keys` list. It verifies every merged partial on both legacy and new sides, drops invalid entries with a stderr warning, then **intersects** the valid signer-index sets across the two sides and selects the first K indices present on BOTH. This is what guarantees `legacy_proof.signer_indices == new_proof.signer_indices`, the consensus-level mirror-source rule. A one-sided partial (e.g. a co-signer who signed only the legacy half because they lost their eth sub-key) does not contribute toward quorum unless another co-signer supplied the new-side signature at the same index. If the intersection has fewer than K entries, combine-proof errors with `need <K> valid partial signatures signed on BOTH sides at matching indices, have <N>` and writes nothing.
 
 #### Step 6 — Coordinator submits the pre-assembled tx
 
-```bash
-lumerad tx evmigration submit-proof tx.json \
-  --chain-id <chain-id>
-```
-
-`submit-proof` broadcasts the pre-assembled tx **without signing at the Cosmos layer**. Migration messages declare zero signers (authorization is fully embedded in `legacy_proof` and `new_proof`), fees are waived by the evmigration ante handler, and replay is prevented by the keeper's `MigrationRecords.Has(legacyAddr)` check. There is no `--from` broadcaster key, no fee-payer, and no envelope signature — `submit-proof` loads `tx.json`, runs `ValidateBasic`, simulates gas via the migration-specific estimator, builds an unsigned tx, and broadcasts.
-
-Verify the migration record:
-
-```bash
-lumerad query evmigration migration-record <multisig-legacy-address>
-```
+Submission is the irreversible boundary. Return to [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once), prove the relevant workload stopped, and submit `tx.json` exactly once with the manifest-pinned absolute chain executable, explicit home/keyring backend/keyring location, exact chain ID, and trusted node used throughout the ceremony. `submit-proof` has no `--from`, fee, or envelope-signature flags. After a tx hash or ambiguous transport failure, apply the runbook's query-before-retry rule; verify the migration record through its manifest-pinned query form.
 
 #### Step 7 — Restart the supernode (local cleanup only)
 
@@ -449,17 +348,7 @@ The new operator account is a Cosmos SDK multisig bech32 derived from `kmultisig
 - The new operator can perform **all** Cosmos-side operations required for supernode life-cycle: `MsgEditSupernode`, validator edits (if applicable), `x/staking` delegations, `x/distribution` withdrawals, `x/authz` grants, and IBC transfers. Every supernode-relevant workflow continues to work.
 - The new operator **cannot** originate `MsgEthereumTx` — multisig bech32 addresses are not valid senders for EVM transactions, and there is no way to produce a single ECDSA signature that authenticates K-of-N.
 
-Operators who want EVM DeFi access for their supernode rewards should configure a separate **single-EOA withdraw address** via:
-
-```bash
-lumerad tx distribution set-withdraw-addr <single-eth-eoa> \
-  --from <new-multisig-key> \
-  --multisig <new-multisig-key> \
-  --chain-id <chain-id> \
-  # ... plus the usual multisig sign/sign-batch/multi-sign/broadcast steps
-```
-
-Rewards then accrue to the single-EOA withdraw address, which **is** EVM-addressable and can originate `MsgEthereumTx` to interact with any EVM contract.
+Operators who want EVM DeFi access for rewards may configure a separate single-EOA withdraw address after migration. This is a new signed transaction, not part of the migration ceremony; execute it only through the same manifest-pinned absolute chain binary and explicit home/keyring backend/keyring location/chain ID/trusted node context, following the platform's complete multisig signing and broadcast procedure. No abbreviated command is provided here.
 
 ### Post-migration cleanup
 
@@ -485,9 +374,9 @@ Regenerate `proof.json` with the correct `--chain-id`, have the affected signer
 
 **What if I only have K−1 of the sub-keys available on the legacy side?** — you can't complete migration. The K-of-N threshold is enforced by the keeper (`need <K> valid partial signatures, have <N>`). Recover the missing legacy sub-key(s) from their mnemonics, or coordinate with the actual holders.
 
-**What if only K−1 co-signers have provided eth sub-keys for the destination side?** — same situation, symmetric: you need K valid new-side partials. Have the missing co-signer(s) generate their eth sub-key (`lumerad keys add ... --key-type eth_secp256k1`), rebuild `proof.json` via `generate-proof-payload` with the full `--new-sub-pub-keys` list, and re-sign.
+**What if only K−1 co-signers have provided eth sub-keys for the destination side?** — same situation, symmetric: you need K valid new-side partials. Have the missing co-signer(s) generate their eth sub-key (`sudo -u <supernode-service-user> "$LUMERAD" keys --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" add ... --key-type eth_secp256k1`), rebuild `proof.json` via `generate-proof-payload` with the full `--new-sub-pub-keys` list, and re-sign.
 
-**`legacy key "..." is signer index N, but new key "..." is signer index M; multisig migration requires the same signer position to approve both halves`** — raised by `sign-proof` when a co-signer passes both `--from` and `--new-key` in one call but the two keys occupy *different* positions in their respective multisigs. Each co-signer must hold the **same signer index** on the legacy and new sides (the consensus mirror-source rule requires `legacy_proof.signer_indices == new_proof.signer_indices`). The usual root cause is a destination multisig built without `--nosort` (so `keys add` sorted the sub-keys) or with a member order that doesn't mirror the legacy `public_keys`. Recreate `<op-name>-msig-new` with `--nosort`, listing the eth sub-keys in the same member order as the legacy multisig (`lumerad query auth account <multisig-legacy-address>`), then regenerate `proof.json` and re-sign.
+**`legacy key "..." is signer index N, but new key "..." is signer index M; multisig migration requires the same signer position to approve both halves`** — raised by `sign-proof` when a co-signer passes both `--from` and `--new-key` in one call but the two keys occupy *different* positions in their respective multisigs. Each co-signer must hold the **same signer index** on the legacy and new sides (the consensus mirror-source rule requires `legacy_proof.signer_indices == new_proof.signer_indices`). The usual root cause is a destination multisig built without `--nosort` (so `keys add` sorted the sub-keys) or with a member order that doesn't mirror the legacy `public_keys`. Recreate `<op-name>-msig-new` with `--nosort`, listing the eth sub-keys in the same member order as the legacy multisig (`sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" auth account <multisig-legacy-address>`), then regenerate `proof.json` and re-sign.
 
 **The supernode's embedded error message says `assemble-proof` but the CLI has `combine-proof`. Which is correct?** — the CLI command is `combine-proof`. Any older embedded error message in the supernode binary is stale; use this guide's commands.
 
diff --git a/docs/evm-integration/user-guides/validator-migration.md b/docs/evm-integration/user-guides/validator-migration.md
index 829e8b85..923b442d 100644
--- a/docs/evm-integration/user-guides/validator-migration.md
+++ b/docs/evm-integration/user-guides/validator-migration.md
@@ -5,6 +5,17 @@
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
 > **Mandatory operations gate:** Run the [EVM Migration Operator Runbook](operator-migration-runbook.md) before this validator procedure. It requires supervisor/user/base-dir/config/keyring discovery, a mode-0600 config backup, verified destination identity, proof that every instance using the consensus key is stopped, one broadcast, and public-address/gRPC/log verification.
+>
+> **Command context used below:** before any CLI example, populate these values from the approved manifest and runbook discovery. `LUMERAD` must be the exact absolute `artifacts.chain_executable.release_path` whose version/tag/commit/hash/source were verified. Each command below passes only flags supported by that command family: tx/query use the explicit home, keyring, chain, and node context; keys use home and keyring context; status uses only the trusted node; and debug address conversion takes no context flags. Do not replace these commands with bare `lumerad` or a universal wrapper.
+>
+> ```bash
+> LUMERAD=/absolute/path/from/approved/artifacts.chain_executable.release_path
+> LUMERA_HOME=/absolute/discovered/lumera/home
+> KEYRING_BACKEND=<test|file|os>
+> KEYRING_DIR=/absolute/discovered/keyring/location
+> CHAIN_ID=<approved-chain-id>
+> TRUSTED_RPC=<trusted-rpc>
+> ```
 
 ---
 
@@ -18,7 +29,7 @@ Validators **must** use `MsgMigrateValidator` (not `MsgClaimLegacyAccount`). The
 
 **This guide's main flow covers the common single-sig validator operator key case.** If your validator operator key is a K-of-N multisig (rare), see the [Multisig validator operator keys](#multisig-validator-operator-keys) section at the end.
 
-> **Note on `systemctl` commands.** This guide uses `systemctl stop/start lumerad` (and `systemctl restart supernode`) as examples. Many validators don't run the node under systemd — Docker/Kubernetes, cosmovisor, runit/s6, or a bare `lumerad start` under a process supervisor are all common. Substitute whatever supervises your node (e.g. `docker stop <container>`, your cosmovisor service unit, or `pkill -f "lumerad start"`). The only invariant that matters: **`lumerad` must not be producing blocks when you broadcast the migration.**
+> **Supervisor stop is mandatory.** Discover the actual supervisor and service/workload identity, then stop and restart only through that supervisor (systemd, Docker, Kubernetes, cosmovisor, runit/s6, or equivalent). Never use an ad hoc process-signal shortcut: a restart policy can immediately respawn the process. Before broadcasting, prove that the supervisor is stopped and that no process, container, pod, or duplicate instance capable of accessing this validator's `priv_validator_key.json` remains. Follow the canonical [Operator Runbook §5](operator-migration-runbook.md#5-stop-and-prove-stopped); if the supervisor cannot be identified or stopped, do not migrate.
 
 ---
 
@@ -45,7 +56,7 @@ The consensus key, voting power at block height, and validator jailing/slashing
 2. **Verify eligibility.** Run the pre-flight estimate:
 
    ```bash
-   lumerad query evmigration migration-estimate <legacy-validator-address>
+   sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-estimate <legacy-validator-address>
    ```
 
    Check for:
@@ -57,14 +68,14 @@ The consensus key, voting power at block height, and validator jailing/slashing
 
 3. **Prepare both keys.** Keep the legacy `secp256k1` key (coin type 118) and prepare an `eth_secp256k1` destination key (coin type 60). It may use the same mnemonic or a different mnemonic. See step 2 below.
 4. **Pick a trusted external RPC.** Your own node will be stopped during the migration broadcast, so route the migration tx through a trusted peer.
-5. **Confirm the validator is healthy *now*.** Sample the active validator set (`lumerad query staking validators --output json | jq '.validators[] | select(.operator_address == "<your-valoper>") | {status, jailed, tokens}'`) and confirm `jailed: false` (and that status is not `BOND_STATUS_UNBONDING`) immediately before the maintenance window. A jail event between checklist completion and migration start is the most common preventable cause of a failed migration window — keep the gap short, and re-run pre-flight just before Step 4.
+5. **Confirm the validator is healthy *now*.** Sample the active validator set (`sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking validators --output json | jq '.validators[] | select(.operator_address == "<your-valoper>") | {status, jailed, tokens}'`) and confirm `jailed: false` (and that status is not `BOND_STATUS_UNBONDING`) immediately before the maintenance window. A jail event between checklist completion and migration start is the most common preventable cause of a failed migration window — keep the gap short, and re-run pre-flight just before Step 4.
 
 ---
 
 ## Step 1 — Check migration parameters
 
 ```bash
-lumerad query evmigration params
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration params
 ```
 
 ```json
@@ -90,10 +101,7 @@ The destination requirements are coin type `60`, key type `eth_secp256k1`, a fre
 Verify both public key records using the exact approved binary/home/backend/location:
 
 ```bash
-sudo -u <validator-service-user> /absolute/approved/lumerad keys list \
-  --home /absolute/lumera/home \
-  --keyring-backend <backend> \
-  --keyring-dir /absolute/keyring/location
+sudo -u <validator-service-user> "$LUMERAD" keys --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" list
 ```
 
 You should see the existing legacy key with pubkey type `/cosmos.crypto.secp256k1.PubKey` and `val-new` with pubkey type `/cosmos.evm.crypto.v1.ethsecp256k1.PubKey`.
@@ -103,7 +111,7 @@ You should see the existing legacy key with pubkey type `/cosmos.crypto.secp256k
 Before stopping the node, confirm the migration will succeed:
 
 ```bash
-lumerad query evmigration migration-estimate <legacy-validator-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-estimate <legacy-validator-address>
 ```
 
 ```json
@@ -123,7 +131,7 @@ lumerad query evmigration migration-estimate <legacy-validator-address>
 
 `would_succeed: true` with `is_validator: true`, `validator_jailed: false`, `validator_status` ∈ {`BOND_STATUS_BONDED`, `BOND_STATUS_UNBONDED`}, and `val_delegation_count + val_unbonding_count + val_redelegation_count <= max_validator_delegations` means you're clear to proceed.
 
-> **A terminal rejection may return *only* `rejection_reason`.** When the account can never be migrated as-is — most commonly because it was **already migrated** — the estimate collapses to a single field, e.g. `{ "rejection_reason": "already migrated" }`, with none of the `is_validator` / `would_succeed` / count fields shown above. The query isn't broken; the condition is terminal. For `already migrated`, look up where it went with `lumerad query evmigration migration-record <legacy-address>` and use the new address going forward. See [Troubleshooting](#troubleshooting).
+> **A terminal rejection may return *only* `rejection_reason`.** When the account can never be migrated as-is — most commonly because it was **already migrated** — the estimate collapses to a single field, e.g. `{ "rejection_reason": "already migrated" }`, with none of the `is_validator` / `would_succeed` / count fields shown above. The query isn't broken; the condition is terminal. For `already migrated`, look up where it went with `sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-address>` and use the new address going forward. See [Troubleshooting](#troubleshooting).
 
 The chain rejects migration in exactly two cases: the validator is **jailed**, or it is still **`BOND_STATUS_UNBONDING`**. A `BOND_STATUS_UNBONDED` validator that is *not* jailed is fully migratable — this is the recovery path for an operator who fell out of the active set on stake weight. The failure shapes you may see:
 
@@ -143,40 +151,39 @@ If the pre-flight reported `validator_jailed: true`, your validator was kicked o
 `unjail` is a **transaction signed by the validator's operator key** (the same key you're trying to migrate). It requires the node to be **running, synced, and able to broadcast**. But migrate-validator requires the node to be **stopped before broadcast** to avoid double-signing risk. So the recovery sequence intentionally restarts the node, runs `unjail`, waits for re-bonding, then stops again before the migration:
 
 ```bash
-# 1. Make sure the validator is running.
-systemctl start lumerad
+# 1. Start through the supervisor identity discovered by the operator runbook.
+<discovered-supervisor-command> start <validator-service-or-workload>
 
 # 2. Wait for it to catch up to the tip. Repeat until catching_up = false.
-lumerad status | jq '.sync_info | {catching_up, latest_block_height}'
+sudo -u <validator-service-user> "$LUMERAD" status --node "$TRUSTED_RPC" | jq '.sync_info | {catching_up, latest_block_height}'
 
 # 3. Submit the unjail transaction (signed with the validator's operator key).
-lumerad tx slashing unjail \
+sudo -u <validator-service-user> "$LUMERAD" tx --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" slashing unjail \
   --from <validator-key> \
-  --chain-id <chain-id> \
-  --keyring-backend <backend> \
   --gas auto --gas-adjustment 1.3 --fees <fee>ulume \
   --yes
 
 # 4. Wait one block, then verify status.
-VALOPER=$(lumerad debug addr <legacy-validator-address> | awk -F': ' '/^Bech32 Val: /{print $2; exit}')
-lumerad query staking validator "$VALOPER" --output json \
+VALOPER=$(sudo -u <validator-service-user> "$LUMERAD" debug addr <legacy-validator-address> | awk -F': ' '/^Bech32 Val: /{print $2; exit}')
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking validator "$VALOPER" --output json \
   | jq '.validator | {status, jailed, tokens, delegator_shares}'
 # Expect: jailed = false. Status BOND_STATUS_BONDED (rebonded) or
 # BOND_STATUS_UNBONDED (not enough stake to rebond) — both are migratable.
 
 # 5. Re-run the pre-flight estimate to confirm migration is now unblocked.
-lumerad query evmigration migration-estimate <legacy-validator-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-estimate <legacy-validator-address>
 # Expect: would_succeed = true.
 
-# 6. Stop the node again before broadcasting the migration (Step 4).
-systemctl stop lumerad
+# 6. Stop through that same discovered supervisor, then repeat its stopped-state
+# and consensus-key process/container/pod proofs before broadcasting (Step 4).
+<discovered-supervisor-command> stop <validator-service-or-workload>
 ```
 
 ### Common failure modes when unjailing
 
-- **`validator still jailed; cannot be unjailed`** — the slashing window hasn't fully elapsed. Wait ~30 s and retry. (The window is `signed_blocks_window` blocks, which on Lumera is parameterized via `slashing` module params; query `lumerad query slashing params` to see the current value.)
-- **`validator missing self-delegation`** — your validator's self-stake fell below `min_self_delegation`. Self-delegate first (`lumerad tx staking delegate <valoper> <amount>`), then retry unjail.
-- **`unauthorized: account does not exist`** — the operator key you're signing with isn't the validator's operator. Confirm `lumerad keys show <validator-key> -a` matches the legacy address you're migrating.
+- **`validator still jailed; cannot be unjailed`** — the slashing window hasn't fully elapsed. Wait ~30 s and retry. (The window is `signed_blocks_window` blocks, which on Lumera is parameterized via `slashing` module params; query `sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" slashing params` to see the current value.)
+- **`validator missing self-delegation`** — your validator's self-stake fell below `min_self_delegation`. Self-delegate first (`sudo -u <validator-service-user> "$LUMERAD" tx --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking delegate <valoper> <amount>`), then retry unjail.
+- **`unauthorized: account does not exist`** — the operator key you're signing with isn't the validator's operator. Confirm `sudo -u <validator-service-user> "$LUMERAD" keys --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" show <validator-key> -a` matches the legacy address you're migrating.
 
 ### What if the validator is `BOND_STATUS_UNBONDED` with `jailed: false`?
 
@@ -219,71 +226,9 @@ Revert this to `"10s"` and restart once the migration is done — see [Step 7](#
 
 ## Step 5 — Broadcast the validator migration
 
-Route the transaction through a trusted external RPC since your own node is down:
-
-```bash
-lumerad tx evmigration migrate-validator val-legacy val-new \
-  --keyring-backend file \
-  --chain-id <chain-id> \
-  --node tcp://<trusted-rpc>:26657
-```
-
-> **Shell helper alternative.** The bundled `scripts/migrate-validator.sh` wraps this command (plus the pre-flight estimate in Step 3, the delegation-cap check, post-migration verification against a pre-broadcast balance snapshot, and the post-migration checklist) into a single safer invocation. Use it when you want one command that enforces the guards rather than running each check by hand:
->
-> ```bash
-> ./scripts/migrate-validator.sh val-legacy val-new \
->   --keyring-backend file \
->   --chain-id <chain-id> \
->   --node tcp://<trusted-rpc>:26657 \
->   --i-have-stopped-the-node
-> ```
->
-> `--i-have-stopped-the-node` acknowledges the jailing risk non-interactively (required for systemd / CI / non-TTY runs; omitting it makes the script prompt for the literal word `yes`). `--yes` alone does **not** satisfy this check. This gate applies to `--dry-run` too: a dry-run from a non-TTY context (a pipe, CI, `docker exec -i`) aborts with `validator downtime not acknowledged and no TTY available` unless you also pass `--i-have-stopped-the-node` — even though a dry-run never broadcasts. See [migration-scripts.md](migration-scripts.md) for full flag reference, exit codes, and troubleshooting.
-
-Example interactive helper run:
-
-```text
-$ ./scripts/migrate-validator.sh validator-legacy validator-evm --node http://172.28.0.11:26657
-INFO  chain ID: lumera-devnet-1
-INFO  legacy key validator-legacy -> address lumera1k0aj0fp28trnnfsn7u2recq7yfnujk7wqj9j4y
-INFO  new EVM key validator-evm -> address lumera1ay0lsu8uw0unswqakvx7ytmdelslkm4vt5nnht
-INFO  check OK: no migration record found for legacy address lumera1k0aj0fp28trnnfsn7u2recq7yfnujk7wqj9j4y
-INFO  check OK: destination address lumera1ay0lsu8uw0unswqakvx7ytmdelslkm4vt5nnht has no migration record as a legacy address
-INFO  check OK: no migration record found by new address lumera1ay0lsu8uw0unswqakvx7ytmdelslkm4vt5nnht
-INFO  check OK: destination address lumera1ay0lsu8uw0unswqakvx7ytmdelslkm4vt5nnht does not exist on-chain
-Migration preview for legacy account lumera1k0aj0fp28trnnfsn7u2recq7yfnujk7wqj9j4y (coin-type 118, secp256k1):
-  Validator:         yes
-  Val delegations:   38 (to validator)
-  Val unbondings:    8 (to validator)
-  Val redelegations: 16 (src or dst)
-  Validator status:  Bonded
-  Jailed:            no
-  Multisig:          no
-  Balance:           999740294121ulume
-  Delegations:       1
-  Unbonding:         none
-  Redelegations:     none
-  Authz grants:      none
-  Feegrants:         none
-  Actions:           none
-  Supernode:         yes
-  Would succeed:     yes
-================================================================
-WARNING - VALIDATOR MIGRATION
-Your validator will miss blocks and may be jailed during
-migration. The node MUST be stopped before broadcasting this tx.
-================================================================
-Type "yes" to confirm the node is stopped: yes
-INFO  migrating legacy validator lumera1k0aj0fp28trnnfsn7u2recq7yfnujk7wqj9j4y -> EVM-compatible lumera1ay0lsu8uw0unswqakvx7ytmdelslkm4vt5nnht
-```
+Do not use a shortened raw-CLI or helper command from this account-specific guide. Return to [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once) and execute its canonical manifest-pinned helper command for the discovered systemd, Docker, or Kubernetes environment. The post-stop dry-run and one live invocation must use the manifest-pinned absolute helper and `lumerad` paths, exact service identity, explicit home, keyring backend and location, chain ID, trusted node, and stopped-node acknowledgement. The live invocation must be identical to the approved dry-run except for removal of `--dry-run`.
 
-The CLI:
-
-1. Reads both keys from the keyring.
-2. Derives both addresses and builds the migration payload `lumera-evm-migration:<chain-id>:<evm-chain-id>:validator:<legacy>:<new>`.
-3. Signs the legacy proof with `val-legacy` (secp256k1).
-4. Signs the new proof with `val-new` (eth_secp256k1).
-5. Simulates gas, asks for confirmation, and broadcasts.
+The helper reads both keys from the selected keyring, derives both addresses, signs the legacy and destination proofs, simulates gas, and broadcasts exactly once. Preserve its transaction hash and public-address output, then apply the runbook's query-before-retry boundary.
 
 On success you'll see `"code": 0` and the `migrate_validator` event in the response:
 
@@ -299,8 +244,7 @@ On success you'll see `"code": 0` and the `migrate_validator` event in the respo
 ## Step 6 — Verify the migration record
 
 ```bash
-lumerad query evmigration migration-record <legacy-validator-address> \
-  --node tcp://<trusted-rpc>:26657
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-validator-address>
 ```
 
 ```json
@@ -317,14 +261,12 @@ lumerad query evmigration migration-record <legacy-validator-address> \
 Confirm the validator's new operator address under the new valoper prefix:
 
 ```bash
-lumerad query staking validator <new-valoper-address> --node tcp://<trusted-rpc>:26657
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking validator <new-valoper-address>
 ```
 
 ## Step 7 — Restart the validator immediately
 
-```bash
-systemctl start lumerad   # or however you supervise the node — see "Note on systemctl commands" in the Overview
-```
+Restart only through the exact supervisor and workload identity discovered in the operator runbook, then prove that exactly one supervised instance is running. Use the runbook's concrete systemd, Docker, or Kubernetes restart-and-verification branch; do not substitute an ad hoc process launch.
 
 > **Warning:** restart promptly after migration. Extended downtime leads to missed blocks and eventual jailing. Use a trusted external RPC for the migration broadcast so you're not blocked on your own node being up.
 
@@ -333,11 +275,11 @@ systemctl start lumerad   # or however you supervise the node — see "Note on s
 Verify the validator is signing blocks:
 
 ```bash
-lumerad query staking validator <new-valoper-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking validator <new-valoper-address>
 # Expect status "BOND_STATUS_BONDED"
 
 # After a few blocks:
-lumerad query slashing signing-info <new-consensus-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" slashing signing-info <new-consensus-address>
 # Confirm missed_blocks_counter isn't growing unboundedly
 ```
 
@@ -353,9 +295,7 @@ If your validator account and your supernode account are the **same entity** (th
 
 After the validator migration and restart, also restart the supernode so it picks up the new key state:
 
-```bash
-systemctl restart supernode
-```
+Restart the SuperNode through its independently discovered supervisor/workload identity and prove exactly one supervised instance is running, following the operator runbook's matching systemd, Docker, or Kubernetes branch.
 
 See [supernode-migration.md](supernode-migration.md) for the supernode daemon's config-update behavior — it detects the on-chain migration record on the next startup and rewrites `config.yml` automatically.
 
@@ -369,22 +309,22 @@ After the migration and restart:
 
 ```bash
 # 1. Migration record exists and maps legacy → new
-lumerad query evmigration migration-record <legacy-validator-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-validator-address>
 
 # 2. New validator is bonded under the new valoper
-lumerad query staking validator <new-valoper-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking validator <new-valoper-address>
 
 # 3. Delegations point at the new valoper (pick any delegator to spot-check)
-lumerad query staking delegations <delegator-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" staking delegations <delegator-address>
 
 # 4. Commission and accumulated rewards are intact at the new address
-lumerad query distribution commission <new-valoper-address>
-lumerad query distribution rewards <delegator-address> <new-valoper-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" distribution commission <new-valoper-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" distribution rewards <delegator-address> <new-valoper-address>
 
 # 5. If running a supernode, confirm record points at the new address.
 #    NOTE: get-supernode takes the VALOPER address (lumeravaloper1…), not the
-#    account address. Convert with: lumerad keys show <new-key> -a --bech val
-lumerad query supernode get-supernode <new-valoper-address>
+#    account address. Convert with: sudo -u <validator-service-user> "$LUMERAD" keys --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" show <new-key> -a --bech val
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" supernode get-supernode <new-valoper-address>
 ```
 
 ---
@@ -398,9 +338,8 @@ Your validator was kicked out of the active set for a slashable offense (almost
 The minimum command, assuming the node is up and synced:
 
 ```bash
-lumerad tx slashing unjail \
+sudo -u <validator-service-user> "$LUMERAD" tx --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" slashing unjail \
   --from <validator-key> \
-  --chain-id <chain-id> \
   --gas auto --gas-adjustment 1.3 --fees <fee>ulume --yes
 ```
 
@@ -426,7 +365,7 @@ Total of (active delegations + unbonding delegations + redelegations) exceeds th
 This operator key was already migrated (migration is one-shot). The estimate returns only this single field — no `is_validator`, `would_succeed`, or counts. Find where it went and use the new address from now on:
 
 ```bash
-lumerad query evmigration migration-record <legacy-validator-address>
+sudo -u <validator-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-validator-address>
 # record.new_address is authoritative — your validator now operates under the
 # valoper derived from that address.
 ```
@@ -435,7 +374,7 @@ If the recorded `new_address` is **not** the EVM key you expected, stop and inve
 
 ### `new address ... already exists on-chain`
 
-The destination EVM key you derived in Step 2 is not fresh — it already has account state on-chain, and the migration refuses to overwrite it. Derive a different coin-type 60 / `eth_secp256k1` key (or, if you intentionally funded it, note that you must instead pick an unused address). See the destination-freshness warning under [Step 2](#step-2--import-both-keys-from-the-same-mnemonic).
+The destination EVM key you derived in Step 2 is not fresh — it already has account state on-chain, and the migration refuses to overwrite it. Derive a different coin-type 60 / `eth_secp256k1` key (or, if you intentionally funded it, note that you must instead pick an unused address). See the destination-freshness warning under [Step 2](#step-2--pre-stage-the-evm-destination-key).
 
 ### `post failed: Post "http://localhost:26657": dial tcp [::1]:26657: connect: connection refused`
 
@@ -461,7 +400,7 @@ This section only applies if your validator's **operator key** is a K-of-N multi
 
 ### Why the single-command path doesn't work
 
-`lumerad tx evmigration migrate-validator` signs with a single `--from` key. A multisig composite can't single-sign, so the command can't drive the migration. Instead, use the four-step offline proof flow with `--kind validator`. The destination **must** also be a K-of-N multisig of `eth_secp256k1` sub-keys — the mirror-source rule (`types.ValidateProofPair`) is a consensus invariant, so migrating a 2-of-3 legacy operator to a single-EOA or 3-of-5 destination is rejected at `ValidateBasic` with `ErrMirrorSourceMismatch` (code 1121).
+`sudo -u <validator-service-user> "$LUMERAD" tx --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migrate-validator` signs with a single `--from` key. A multisig composite can't single-sign, so the command can't drive the migration. Instead, use the four-step offline proof flow with `--kind validator`. The destination **must** also be a K-of-N multisig of `eth_secp256k1` sub-keys — the mirror-source rule (`types.ValidateProofPair`) is a consensus invariant, so migrating a 2-of-3 legacy operator to a single-EOA or 3-of-5 destination is rejected at `ValidateBasic` with `ErrMirrorSourceMismatch` (code 1121).
 
 > **Consensus invariants (multisig validator).** The chain rejects a multisig validator migration tx at `ValidateBasic` if any of these is violated:
 >
@@ -474,84 +413,13 @@ This section only applies if your validator's **operator key** is a K-of-N multi
 
 ### Flow overview
 
-1. Verify the multisig pubkey is registered on-chain (if never signed a tx, submit a 1-ulume self-send first):
-
-   ```bash
-   lumerad query auth account <multisig-valoper-as-acc-address>
-   ```
-
-   The response must show a `multisig` pubkey listing all N sub-keys.
+The multisig ceremony remains a seven-stage process: prove the legacy multisig pubkey is registered; pre-stage N fresh destination sub-keys; derive the same-K/same-N destination composite without sorting; generate the validator proof payload; collect matching-index signatures on both sides; stop and prove the validator stopped; combine, submit once, restart, and verify.
 
-2. **Each co-signer generates a fresh `eth_secp256k1` sub-key** in their own keyring:
-
-   ```bash
-   lumerad keys add val-eth-<N> --key-type eth_secp256k1 --keyring-backend file
-   ```
-
-   The coordinator collects the N eth pubkeys (or local key-names, if sub-signers share a keyring), then derives the destination composite:
-
-   ```bash
-   lumerad keys add val-msig-new \
-     --multisig val-eth-1,val-eth-2,val-eth-3 \
-     --multisig-threshold 2 \
-     --nosort \
-     --keyring-backend file
-
-   lumerad keys show val-msig-new --address
-   # lumera1...  <-- this is the new operator address
-   ```
-
-   > **`--nosort` is required, and member order matters.** Without `--nosort`, `keys add` sorts the sub-keys by address, so the composite address here would not match the one `generate-proof-payload` derives from `--new-sub-pub-keys` (which preserves listed order) — and the signer indices would not line up with the legacy side. List the members in the **same order as the legacy multisig's `public_keys`** (see `lumerad query auth account <multisig-legacy-address>`), so each participant occupies the same signer index on both sides. The consensus mirror-source rule requires `legacy_proof.signer_indices == new_proof.signer_indices`.
-
-3. **Coordinator generates the proof payload** with `--kind validator`:
-
-   ```bash
-   lumerad tx evmigration generate-proof-payload \
-     --legacy <multisig-legacy-address> \
-     --new-sub-pub-keys val-eth-1,val-eth-2,val-eth-3 \
-     --new-threshold 2 \
-     --kind validator \
-     --chain-id <chain-id> \
-     --keyring-backend file \
-     --out proof.json
-   ```
-
-   `--chain-id` is **required** — the signed payload embeds it. `generate-proof-payload` needs keyring access to resolve `--new-sub-pub-keys` key names, so pass `--keyring-backend` (and `--keyring-dir` / `--home` when applicable). Mirror-source rule: `--new-threshold` must equal the legacy threshold K and the number of entries in `--new-sub-pub-keys` must equal the legacy N; the CLI rejects a mismatch before writing `proof.json`.
-
-4. **Each co-signer signs both sides** in a single invocation (legacy sub-key + destination eth sub-key):
-
-   ```bash
-   lumerad tx evmigration sign-proof proof.json \
-     --from    <my-legacy-sub-key> \
-     --new-key <my-eth-sub-key> \
-     --keyring-backend file \
-     --chain-id <chain-id> \
-     --out my-partial.json
-   ```
-
-   At least one of `--from` / `--new-key` is required; a co-signer who holds only one sub-key passes only that flag. Re-running is idempotent (replaces the signer's prior entries on the corresponding side).
-
-5. **Stop the validator** before broadcasting:
-
-   ```bash
-   systemctl stop lumerad
-   ```
-
-6. **Coordinator combines partials and broadcasts**:
-
-   ```bash
-   lumerad tx evmigration combine-proof \
-     alice-partial.json bob-partial.json \
-     --out tx.json
-
-   lumerad tx evmigration submit-proof tx.json \
-     --chain-id <chain-id> \
-     --node tcp://<trusted-rpc>:26657 -y
-   ```
+Do not execute a shortened `lumerad` command copied from this guide. Each participant and the coordinator must return to the [Operator Runbook](operator-migration-runbook.md), verify the manifest-pinned absolute `artifacts.chain_executable.release_path`, and invoke it with explicit `--home`, `--keyring-backend`, `--keyring-dir`, `--chain-id`, and `--node` as applicable to that stage. The final submit must occur only after the runbook's stopped-node proof and must use the same trusted node and chain ID as the approved ceremony. Treat every proof file and public key list as custody-sensitive evidence and apply the runbook's query-before-retry rule after submission.
 
-   `submit-proof` does **not** sign at the Cosmos layer — migration messages declare zero signers, fees are waived by the evmigration ante handler. There is no `--from`.
+The command semantics and proof-file fields are documented in [legacy-migration.md](../evmigration/legacy-migration.md), but its abbreviated examples are not an execution substitute for the manifest-pinned runbook context. In particular, preserve legacy member order with `--nosort`; use `--kind validator`; keep K, N, and signer indices identical across both proof halves; and never add `--from`, fee, or envelope-signature flags to `submit-proof`.
 
-7. **Restart the validator** and verify as in steps 6–7 of the single-sig flow. Note: the queryable operator address is now the new multisig bech32 (`val-msig-new`), not an EOA.
+After successful submission, restart through the discovered supervisor and verify as in steps 6–7 of the single-sig flow. The queryable operator address is now the destination multisig bech32, not an EOA.
 
 `combine-proof` verifies each partial under its sub-pub-key on **both sides**, skips invalid entries, then **intersects** the valid signer-index sets across the two sides and selects the first K indices present on BOTH. This is what makes `legacy_proof.signer_indices == new_proof.signer_indices` (the consensus mirror-source rule). A co-signer who signs only one side (e.g. lost access to their eth sub-key) doesn't contribute toward quorum unless another co-signer supplies the other side's signature at the same index. If the intersection has fewer than K entries, combine-proof errors with `need <K> valid partial signatures signed on BOTH sides at matching indices, have <N>` and writes nothing.
 

From cab6cecd23dcd8a807c1cfcd00db71d581c830f6 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 04:35:55 +0000
Subject: [PATCH 03/11] docs(evmigration): bind final operator provenance paths

---
 .../compatibility-manifest.schema.json        |  12 +-
 .../compatibility-manifest.template.json      |  23 +-
 docs/evm-integration/user-guides/migration.md | 310 ++----------------
 .../user-guides/operator-migration-runbook.md |  57 +++-
 .../user-guides/relayer-migration.md          |  71 ++--
 .../user-guides/supernode-migration.md        | 188 +----------
 .../user-guides/validator-migration.md        |   6 +-
 7 files changed, 161 insertions(+), 506 deletions(-)

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
index d6c9fc78..8c131e52 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -40,11 +40,12 @@
     "artifacts": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["chain_executable", "supernode_executable", "sncli_executable", "container_image", "bound_files"],
+      "required": ["chain_executable", "supernode_executable", "sncli_executable", "relayer_executable", "container_image", "bound_files"],
       "properties": {
         "chain_executable": { "$ref": "#/$defs/executable" },
         "supernode_executable": { "$ref": "#/$defs/executable" },
         "sncli_executable": { "$ref": "#/$defs/executable" },
+        "relayer_executable": { "$ref": "#/$defs/executable" },
         "container_image": { "$ref": "#/$defs/container_image" },
         "bound_files": {
           "type": "object",
@@ -158,6 +159,7 @@
         }
       },
       "then": {
+        "not": { "required": ["_signing_blocker"] },
         "properties": {
           "release": {
             "properties": {
@@ -206,6 +208,9 @@
               "release_owner_approved": { "const": true },
               "detached_signature": { "$ref": "#/$defs/approved_signature" }
             }
+          },
+          "_verification": {
+            "items": { "$ref": "#/$defs/non_placeholder" }
           }
         }
       }
@@ -228,8 +233,9 @@
     "file": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["sha256", "source"],
+      "required": ["release_path", "sha256", "source"],
       "properties": {
+        "release_path": { "type": "string", "minLength": 1 },
         "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
         "source": { "type": "string", "minLength": 1 }
       }
@@ -237,6 +243,7 @@
     "approved_file": {
       "type": "object",
       "properties": {
+        "release_path": { "$ref": "#/$defs/non_placeholder" },
         "sha256": { "$ref": "#/$defs/sha256" },
         "source": { "$ref": "#/$defs/non_placeholder" }
       }
@@ -341,6 +348,7 @@
         "chain_executable": { "$ref": "#/$defs/approved_executable" },
         "supernode_executable": { "$ref": "#/$defs/approved_executable" },
         "sncli_executable": { "$ref": "#/$defs/approved_executable" },
+        "relayer_executable": { "$ref": "#/$defs/approved_executable" },
         "container_image": { "$ref": "#/$defs/approved_container_image" },
         "bound_files": {
           "properties": {
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
index cd2066b4..16402ba4 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -39,6 +39,15 @@
       "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
       "source": "REPLACE_WITH_SNCLI_RELEASE_ASSET_URL"
     },
+    "relayer_executable": {
+      "name": "hermes",
+      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_HERMES",
+      "version": "REPLACE_WITH_HERMES_VERSION",
+      "tag": "REPLACE_WITH_HERMES_RELEASE_TAG",
+      "commit": "0000000000000000000000000000000000000000",
+      "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "source": "REPLACE_WITH_HERMES_RELEASE_ASSET_URL"
+    },
     "container_image": {
       "artifact": "REPLACE_WITH_CONTAINER_IMAGE_REPOSITORY_AND_TAG",
       "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
@@ -46,50 +55,62 @@
     },
     "bound_files": {
       "scripts/evmigration-common.sh": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/evmigration-common.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/evmigration-common.sh"
       },
       "scripts/migrate-account.sh": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-account.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-account.sh"
       },
       "scripts/migrate-validator.sh": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-validator.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-validator.sh"
       },
       "scripts/migrate-multisig.sh": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-multisig.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-multisig.sh"
       },
       "scripts/migrate-batch.sh": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-batch.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-batch.sh"
       },
       "docs/evm-integration/user-guides/operator-migration-runbook.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/operator-migration-runbook.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/operator-migration-runbook.md"
       },
       "docs/evm-integration/user-guides/migration.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration.md"
       },
       "docs/evm-integration/user-guides/migration-scripts.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration-scripts.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration-scripts.md"
       },
       "docs/evm-integration/user-guides/validator-migration.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/validator-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/validator-migration.md"
       },
       "docs/evm-integration/user-guides/supernode-migration.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/supernode-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/supernode-migration.md"
       },
       "docs/evm-integration/user-guides/relayer-migration.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/relayer-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/relayer-migration.md"
       },
       "docs/evm-integration/evmigration/legacy-migration.md": {
+        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/evmigration/legacy-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/evmigration/legacy-migration.md"
       }
@@ -151,7 +172,7 @@
   },
   "_verification": [
     "Release owner: replace every REPLACE_WITH value and every all-zero commit/hash; approval.status=approved is schema-invalid while any remain.",
-    "Extract each release asset into a new mode-0700 directory. Verify the chain, SuperNode, and sncli executable release path, tag, commit, version, source, and SHA-256; verify the container image artifact, registry source, and immutable digest; then verify every artifacts.bound_files entry individually with sha256sum.",
+    "Extract each release asset into a new mode-0700 directory. Verify the chain, SuperNode, sncli, and Hermes executable release path, tag, commit, version, source, and SHA-256; verify the container image artifact, registry source, and immutable digest; then verify every artifacts.bound_files release_path individually with sha256sum.",
     "Require operator_contracts.destination_prestage_no_echo.status=verified and bind its implementation name, tag, commit, SHA-256, source, and exact no-echo contract. Do not approve an unfinished or narrative-only PR-2 dependency.",
     "Run every validation command and attach sanitized evidence. Every validation status, including owned_testnet and portal_live, must be pass before approval is schema-valid.",
     "Validate the schema under draft 2020-12, validate this manifest against it, and confirm a copy changed to approval.status=approved while retaining any blocked/postponed/placeholder field is rejected.",
diff --git a/docs/evm-integration/user-guides/migration.md b/docs/evm-integration/user-guides/migration.md
index aebe3177..38f6105a 100644
--- a/docs/evm-integration/user-guides/migration.md
+++ b/docs/evm-integration/user-guides/migration.md
@@ -129,7 +129,7 @@ record count.
   in [validator-migration.md](validator-migration.md) — your own node is stopped
   during broadcast, so this change goes on the **trusted external RPC** node.
 
-For step-by-step instructions see [§ Single-sig validator migration](#single-sig-validator-migration) (Method 2) and [§ Post-Migration for Validators](#5-post-migration-for-validators) (Method 3). For maintenance-window planning, consensus-key safety, and the multisig variant, see [validator-migration.md](validator-migration.md).
+For the release-pinned one-shot procedure, maintenance-window planning, consensus-key safety, post-migration restart, and the multisig variant, see [validator-migration.md](validator-migration.md) and the mandatory [Operator Runbook](operator-migration-runbook.md).
 
 ---
 
@@ -287,7 +287,7 @@ The result screen now embeds the complete post-migration checklist so you can fi
 - **3. Switch the Portal to Lumera EVM, reconnect Keplr, then add an existing wallet with the same recovery phrase** — the ordered sub-steps (a–e) that the Claim/EVM Migration page also walks you through after you close the dialog.
 - **Tx** — the on-chain transaction hash, with copy and explorer-link buttons.
 
-**For validators**: an urgent section shows the restart command (`systemctl start lumerad`). Restart your validator promptly to avoid missed blocks and jailing.
+**For validators**: the Portal may display a host-specific restart hint. Ignore it unless it exactly matches the supervisor discovered in the mandatory runbook; restore the validator through [Operator Runbook §8](operator-migration-runbook.md#8-finalize-restart-and-verify).
 
 Click **DONE** to close the wizard. The **EVM Migration** page now switches into the post-migration follow-up flow described next.
 
@@ -304,7 +304,7 @@ Click **DONE** to close the wizard. The **EVM Migration** page now switches into
 > 5. Repeat steps 3–4 for every legacy account you have.
 > 6. **Only once every legacy account is migrated**, follow the post-migration cleanup once: switch Portal to the EVM profile, refresh Keplr's chain registration, and then re-import the mnemonic(s) into fresh Keplr profile(s) to expose the migrated EVM-derived addresses for each account.
 >
-> **Many accounts? Use the shell helpers instead.** Once you're past a handful of legacy accounts, clicking through the Portal+Keplr wizard for each one becomes the bottleneck — and Keplr's signature popups can't be automated. Switch to the bundled [`scripts/migrate-account.sh`](#method-2-shell-helper-scripts) (or `migrate-validator.sh` for validators), which run the same migration non-interactively from a keyring. They're easy to drop into a loop over a list of legacy key names, produce structured exit codes for each result, and capture pre/post balance snapshots — so a batch migration is auditable rather than something you have to retrace by hand.
+> **Many accounts require a separately reviewed batch plan.** Use only the exact manifest-bound batch/helper `release_path` through [Method 2](#method-2-release-pinned-shell-helpers) and its matching method guide. Preserve the same destination-prestage, stopped-state, dry-run, one-broadcast, and query-before-retry gates for every account; do not improvise a loop around an abbreviated command.
 
 #### 5. Post-Migration Follow-Up on the EVM Migration Page
 
@@ -435,223 +435,25 @@ You switched Keplr accounts or profiles between wizard steps. Go back to Step 1
 
 ---
 
-## Method 2: Shell Helper Scripts
+## Method 2: Release-Pinned Shell Helpers
 
-The repository ships two bash wrappers in [scripts/](../../../scripts/) that layer safety rails on top of the Method 3 CLI flow:
+The release includes single-account and validator helpers, but this guide intentionally does not duplicate executable invocations. A shortened command can silently select the wrong binary, helper file, home, or keyring.
 
-- `scripts/migrate-account.sh` — regular account migration (`claim-legacy-account`)
-- `scripts/migrate-validator.sh` — validator migration (`migrate-validator`)
-
-Both scripts:
-
-- Detect and reject multisig accounts (use the offline 4-step flow in[legacy-migration.md](../evmigration/legacy-migration.md#multisig-account-migration) for those).
-- Run `migration-estimate` before broadcast so you see what moves and why it might fail.
-- Compare post-migration balances against a pre-broadcast snapshot.
-
-The abbreviated invocations below cover the common cases. For the full reference — all flags, exit codes, troubleshooting keyed by exit code, fresh-destination-key flow, and non-interactive / CI usage — see [migration-scripts.md](migration-scripts.md).
-
-### Single-sig account migration
-
-```bash
-./scripts/migrate-account.sh legacy-key new-key \
-  --chain-id lumera-mainnet-1 \
-  --node tcp://rpc.lumera:26657 \
-  --keyring-backend test
-```
-
-Use `--mnemonic-file <path>` (mode `0600`) as an optional convenience when both derivations intentionally use one mnemonic. Otherwise import the keys separately. Add `--dry-run` to preview without broadcasting.
-
-### Single-sig validator migration
-
-```bash
-./scripts/migrate-validator.sh legacy-op-key new-evm-key \
-  --chain-id lumera-mainnet-1 \
-  --node tcp://rpc.lumera:26657 \
-  --keyring-backend test \
-  --i-have-stopped-the-node
-```
-
-`--i-have-stopped-the-node` acknowledges the jailing risk; omitting it makes the script prompt interactively. `--yes` does NOT satisfy this acknowledgement — that's deliberate.
-
-### Exit codes
-
-| Code   | Meaning                                                                                     |
-| ------ | ------------------------------------------------------------------------------------------- |
-| `0`  | Success, or dry-run completed cleanly                                                       |
-| `1`  | Usage error / bad flags / bad input file permissions / key name collision                   |
-| `2`  | Environment error: binary missing, jq missing, node unreachable, unsupported binary version |
-| `3`  | Multisig rejected; use offline flow                                                         |
-| `4`  | Pre-flight estimate returned `would_succeed=false`                                        |
-| `5`  | Account already migrated (or new address already used)                                      |
-| `6`  | Wrong-script or delegation-cap error                                                        |
-| `7`  | Broadcast succeeded but post-migration verification failed — investigate manually          |
-| `10` | User aborted at a confirmation prompt                                                       |
+For any terminal migration, execute the exact manifest-bound helper `release_path` and chain executable through [Operator Runbook §2](operator-migration-runbook.md#2-pin-binary-home-and-keyring-provenance), then use the matching systemd/host, Docker, or Kubernetes one-shot branch in [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once). The helper's flags, exit-code semantics, and account-specific preparation remain documented in [migration-scripts.md](migration-scripts.md), but the runbook's provenance, destination-prestage, stop, dry-run, and single-broadcast gates are mandatory.
 
 ---
 
-## Method 3: Lumera CLI
-
-The CLI requires both keys (legacy and new) in the keyring. It handles address derivation, proof signing, gas simulation, and broadcasting automatically.
-
-### CLI Prerequisites
-
-- `lumerad` binary (post-EVM upgrade version)
-- Your mnemonic (recovery phrase)
-- Access to a running Lumera node (local or remote RPC endpoint)
-
-### CLI Step-by-Step
-
-Both keys must be in the keyring. The CLI extracts the public key, generates both proofs, and broadcasts automatically.
-
-#### 1. Pre-flight: Check Migration Eligibility
-
-```bash
-# Check if migration is enabled
-lumerad query evmigration params --node <rpc-endpoint>
-
-# Check migration estimate for your legacy address
-lumerad query evmigration migration-estimate <legacy-address> --node <rpc-endpoint>
-```
-
-The estimate response shows `would_succeed: true` if migration is possible. If `would_succeed: false`, the `rejection_reason` field explains why.
-
-```bash
-# Check overall migration statistics
-lumerad query evmigration migration-stats --node <rpc-endpoint>
-```
-
-#### 2. Prepare the EVM Destination Key
-
-**Import the legacy key (coin-type 118, secp256k1):**
-
-```bash
-lumerad keys add legacy-key \
-  --recover \
-  --coin-type 118 \
-  --key-type secp256k1 \
-  --keyring-backend test
-```
-
-Enter your mnemonic when prompted.
-
-**Import the new EVM key (coin-type 60, eth_secp256k1):**
-
-```bash
-lumerad keys add new-key \
-  --coin-type 60 \
-  --key-type eth_secp256k1 \
-  --keyring-backend test
-```
-
-Securely back up the generated mnemonic. Alternatively, use `--recover` with an existing mnemonic; it may be the legacy mnemonic or a different one.
-
-**Verify the addresses:**
-
-```bash
-lumerad keys show legacy-key -a --keyring-backend test
-lumerad keys show new-key -a --keyring-backend test
-```
-
-The legacy address should match your known pre-EVM address on chain.
-
-#### 3. Run the Migration
-
-**For regular account migration:**
+## Method 3: Direct Lumera CLI
 
-```bash
-lumerad tx evmigration claim-legacy-account legacy-key new-key \
-  --keyring-backend test \
-  --chain-id lumera-mainnet-1 \
-  --node tcp://localhost:26657 \
-```
+The direct CLI exposes the underlying query, key, proof, and broadcast semantics, but bare `lumerad` examples are not an approved production procedure. Production operators must use the manifest-pinned absolute chain executable and explicit service identity, home, keyring backend/location, chain ID, and trusted RPC established by the [Operator Runbook](operator-migration-runbook.md).
 
-**For validator migration:**
-
-```bash
-lumerad tx evmigration migrate-validator legacy-validator-key new-validator-evm-key \
-  --keyring-backend test \
-  --chain-id lumera-mainnet-1 \
-  --node tcp://localhost:26657 \
-```
-
-The CLI will:
-
-1. Read both keys from the keyring, extract public keys, and derive bech32 addresses
-2. Verify the legacy key is `secp256k1` (coin-type 118)
-3. Build the migration payload and sign `SHA256(payload)` with the legacy key
-4. Sign the new proof with the new key (must be `eth_secp256k1`)
-5. Build an unsigned, fee-free Cosmos transaction
-6. Simulate gas usage automatically
-7. Prompt for confirmation (unless `--yes` flag is used)
-8. Broadcast the transaction
-
-#### 4. Verify the Migration
-
-```bash
-# Check that the migration record exists
-lumerad query evmigration migration-record <legacy-address> --node <rpc-endpoint>
-
-# Verify balances moved to the new address
-lumerad query bank balances <new-address> --node <rpc-endpoint>
-
-# Confirm legacy address has zero balance
-lumerad query bank balances <legacy-address> --node <rpc-endpoint>
-```
-
-#### 5. Post-Migration for Validators
-
-After a successful validator migration, update your node immediately:
-
-```bash
-# 1. Import the new key into the node's production keyring if not already present
-lumerad keys add new-operator-key \
-  --recover \
-  --coin-type 60 \
-  --algo eth_secp256k1 \
-  --keyring-backend file
-
-# 2. Restart the validator node (or however you supervise it: docker, cosmovisor, etc.)
-systemctl start lumerad
-```
-
-> **Warning:** Your validator will miss blocks and may be jailed if you do not restart promptly after migration. Plan a maintenance window before initiating validator migration.
-
-#### 6. Clean Up
-
-After verifying the migration was successful:
-
-```bash
-lumerad keys delete legacy-key --keyring-backend test
-```
+For single-signature accounts and validators, prefer the release-pinned one-shot helper path in [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once). For command semantics or troubleshooting, consult [legacy-migration.md](../evmigration/legacy-migration.md); do not copy its low-level examples without applying the runbook execution context. Validator stop/restart and final verification are defined in [validator-migration.md](validator-migration.md).
 
 ---
 
-## Quick Reference: Query Commands
-
-These queries are useful before, during, and after migration:
+## Quick Reference: Migration Queries
 
-```bash
-# Module parameters (is migration enabled? deadline?)
-lumerad query evmigration params
-
-# Pre-flight estimate (what will be migrated, will it succeed?)
-lumerad query evmigration migration-estimate <legacy-address>
-
-# Migration record (has this address been migrated?)
-lumerad query evmigration migration-record <legacy-address>
-
-# Reverse lookup (find migration record by new address)
-lumerad query evmigration migration-record-by-new-address <new-address>
-
-# Global statistics (how many accounts migrated/remaining?)
-lumerad query evmigration migration-stats
-
-# List legacy accounts still needing migration
-lumerad query evmigration legacy-accounts --limit 100
-
-# List completed migrations
-lumerad query evmigration migrated-accounts --limit 100
-```
+The module exposes parameter, estimate, migration-record, reverse-record, global-statistics, remaining-account, and completed-account queries. Run those queries only with the manifest-pinned absolute executable and the explicit supported flags shown in [Operator Runbook §7](operator-migration-runbook.md#7-retry-boundary-query-before-any-retry); do not use an unpinned quick-reference command during a production campaign.
 
 ---
 
@@ -683,13 +485,9 @@ Key facts (repeated here for quick reference):
 
 ## Supernode Operator Migration
 
-Supernode operators have their own step-by-step walkthrough covering the automatic startup-migration path for single-sig supernodes and the manual `lumerad` CLI path for multisig supernodes — see [supernode-migration.md](supernode-migration.md).
+This release approves only the manual one-shot migration path in the [Operator Runbook](operator-migration-runbook.md), followed by a supervised restart for local cleanup after the on-chain migration record is verified. Although the daemon contains an automatic startup-broadcast path, that path is **NOT APPROVED by this runbook or release campaign** because no exact supervisor-specific automatic-path rehearsal exists. Do not set `evm_key_name` and restart in order to broadcast.
 
-Key facts:
-
-- The supernode daemon performs automatic migration on startup when `evm_key_name` is set in `config.yml` and the supernode's legacy key is single-sig.
-- For multisig supernode accounts, the daemon refuses and directs you to the offline 4-step `lumerad` CLI ceremony (`generate-proof-payload` →`sign-proof` →`combine-proof` →`submit-proof`). Restart the supernode after the offline ceremony completes — the daemon detects the on-chain migration record and drives local cleanup.
-- If you run a supernode on the same account as a validator operator, migrate the validator (`MsgMigrateValidator` handles the supernode side as a side-effect), then restart both `lumerad` and the supernode.
+For multisig supernode accounts, use the manifest-pinned multisig helper ceremony described in [migration-scripts.md](migration-scripts.md#multisig-migration), then apply the same query-before-retry and supervised-cleanup rules. If the SuperNode account is also a validator operator, follow [validator-migration.md](validator-migration.md); `MsgMigrateValidator` handles the SuperNode record as a side effect.
 
 ## FAQ
 
@@ -725,7 +523,7 @@ The `max_validator_delegations` parameter (default 2500) limits how many records
 
 ## Migrating a multisig account
 
-> **Script wrapper available.** The bundled `scripts/migrate-multisig.sh` layers pre-flight, file-integrity, and post-broadcast verification onto each of the four steps below. For day-to-day use, prefer the script walkthrough at [migration-scripts.md → Multisig migration](migration-scripts.md#multisig-migration). The raw-CLI reference that follows is the canonical source for field semantics and remains useful when debugging.
+> **Production execution:** Use the exact manifest-bound `migrate-multisig.sh` `release_path` through [migration-scripts.md → Multisig migration](migration-scripts.md#multisig-migration) and the [Operator Runbook](operator-migration-runbook.md). The conceptual notes below explain the proof invariants; they are not a substitute command source.
 
 Multisig legacy accounts (flat K-of-N `secp256k1`) use an offline, coordinator-driven flow with four commands. The portal wizard does not support multisig — use the CLI.
 
@@ -757,11 +555,7 @@ The payload is identical across all co-signers; what differs is whose sub-key si
 
 **Why a multisig pubkey can be missing.** A Cosmos account only records its public key when the account *signs* an accepted transaction. An account funded at genesis, or one that has only ever *received* funds, exists on-chain with no pubkey stored. The bech32 address alone never reveals whether it was derived from a single key or a multisig — that becomes knowable only after the account signs once. This bites genesis-funded multisigs in particular: they hold a balance and look ready to migrate, but the chain has nothing to verify against.
 
-**How to recognize the unseeded state.** Query the account:
-
-```bash
-lumerad query auth account <multisig-legacy-address>
-```
+**How to recognize the unseeded state.** Query the account through the runbook's manifest-pinned chain executable and explicit trusted-node context.
 
 - `pub_key` is a `/cosmos.crypto.multisig.LegacyAminoPubKey` with a `public_keys` list → seeded; proceed with migration.
 - `pub_key: null` **and** `sequence: "0"` → the account has never signed; the multisig pubkey is not seeded. Seed it (below) before migrating.
@@ -769,24 +563,7 @@ lumerad query auth account <multisig-legacy-address>
 
 **Seeding is itself a K-of-N multisig transaction.** "Submit any transaction first" is the right idea, but for, say, a 2-of-3 multisig the seeding tx must itself be signed by at least K members and assembled as a multisig tx — a single member cannot seed it alone. A 1-ulume self-send (multisig → the same multisig address) is the cheapest option: the send amount returns to the account and only the fee is spent.
 
-```bash
-# 1. Build the unsigned self-send (use the multisig's keyring key name).
-lumerad tx bank send <multisig-key> <multisig-legacy-address> 1ulume \
-  --generate-only --chain-id <chain-id> > seed.json
-
-# 2. K members each sign independently (--multisig takes the multisig address).
-lumerad tx sign seed.json --from <member-1> --multisig <multisig-legacy-address> \
-  --chain-id <chain-id> --output-document sig1.json
-lumerad tx sign seed.json --from <member-2> --multisig <multisig-legacy-address> \
-  --chain-id <chain-id> --output-document sig2.json
-
-# 3. Combine the K signatures under the multisig key.
-lumerad tx multisign seed.json <multisig-key> sig1.json sig2.json \
-  --chain-id <chain-id> > seed-signed.json
-
-# 4. Broadcast. Once included, the chain stores the multisig pubkey.
-lumerad tx broadcast seed-signed.json --node <rpc-url>
-```
+The exact K-of-N self-send build, member-sign, multisign, and broadcast procedure must come from the manifest-pinned multisig method guide. Treat its broadcast as an irreversible boundary and apply query-before-retry.
 
 Re-run the `auth account` query and confirm `pub_key` is now a `LegacyAminoPubKey` listing all sub-keys.
 
@@ -801,32 +578,12 @@ When using raw `lumerad tx broadcast`, inspect the returned JSON `code`. The CLI
 
 ### Step 1: Coordinator generates the proof payload template
 
-The destination of a K-of-N legacy multisig is **also** a K-of-N multisig, built from fresh `eth_secp256k1` sub-keys (mirror-source rule — see [evmigration/main.md → Multisig account migration](../evmigration/main.md#multisig-account-migration)). Each co-signer generates their own eth sub-key; the coordinator collects the N eth pubkeys (or local key-names) and runs:
-
-```bash
-lumerad tx evmigration generate-proof-payload \
-  --legacy <multisig-bech32> \
-  --new-sub-pub-keys <eth-k1>,<eth-k2>,<eth-k3> \
-  --new-threshold    2 \
-  --kind claim \
-  --chain-id <chain-id> \
-  --keyring-backend <backend> \
-  --out proof.json
-```
+The destination of a K-of-N legacy multisig is **also** a K-of-N multisig, built from fresh `eth_secp256k1` sub-keys (mirror-source rule — see [evmigration/main.md → Multisig account migration](../evmigration/main.md#multisig-account-migration)). Each co-signer generates their own eth sub-key; the coordinator collects the N eth pubkeys (or local key names) and creates the payload with the manifest-pinned multisig helper and explicit runbook execution context.
 
 - `--new-sub-pub-keys` entries are either local keyring key names (eth_secp256k1) or base64-encoded 33-byte compressed eth pubkeys. Mix freely. `--new-threshold` is required with `--new-sub-pub-keys`.
 - **Member order is significant — pass `--nosort` when building the destination key.** `generate-proof-payload` preserves the order you list `--new-sub-pub-keys` (it does not sort), and the signer index is the position in that list. Because the mirror-source rule requires `legacy_proof.signer_indices == new_proof.signer_indices`, list the eth sub-keys in the **same member order as the legacy multisig's `public_keys`** (`lumerad query auth account <multisig-bech32>`), so each co-signer holds the same signer index on both sides.
 
-  > **⚠️ When pre-creating the destination composite with `lumerad keys add --multisig`, you MUST pass `--nosort`.** The default behavior is to sort sub-pubkeys by bytes, and because legacy `secp256k1` and new `eth_secp256k1` pubkey bytes sort differently, the default sort produces a destination whose member order does not mirror the legacy side. Co-signers will then fail at `sign-proof` with a "signer index mismatch" error and you'll have to rebuild the destination key and regenerate `proof.json`. Always:
-  >
-  > ```bash
-  > lumerad keys add <new-multisig-key> \
-  >   --multisig=<eth-sub-1>,<eth-sub-2>,...,<eth-sub-N> \
-  >   --multisig-threshold=<K> \
-  >   --nosort
-  > ```
-  >
-  > where the `<eth-sub-i>` order matches the legacy multisig's on-chain `public_keys` order.
+  > **⚠️ Destination construction must disable member sorting.** The default byte sort can reorder legacy and destination members differently. Follow the exact `--nosort` construction in the manifest-pinned multisig method guide, preserving the legacy on-chain `public_keys` order.
   >
 - For same-mnemonic migrations, signer index 0's legacy mnemonic should be used to recover signer index 0's EVM sub-key, signer index 1's legacy mnemonic should be used for signer index 1's EVM sub-key, and so on. Reordering the same EVM sub-keys produces a different destination multisig address.
 - `--new <bech32>` is optional; the CLI derives the new multisig address from the sub-keys/threshold and cross-checks `--new` if supplied.
@@ -839,16 +596,7 @@ The output `proof.json` is a v2 `PartialProof` with two sibling `SideSpec`s (`le
 
 ### Step 2: Each co-signer signs both sides on their own machine
 
-Each co-signer holds their legacy Cosmos sub-key **and** their destination-side eth sub-key in the same keyring, and signs both sides in one invocation:
-
-```bash
-lumerad tx evmigration sign-proof proof.json \
-  --from    <my-legacy-sub-key> \
-  --new-key <my-eth-sub-key> \
-  --keyring-backend <backend> \
-  --chain-id <chain-id> \
-  --out my-partial.json
-```
+Each co-signer holds their legacy Cosmos sub-key **and** destination-side eth sub-key in the same explicit keyring and signs both sides through the manifest-pinned multisig helper.
 
 - `--from` signs the legacy half; `--new-key` signs the new half. At least one is required. A co-signer who holds only one sub-key may pass just that flag, but **one-sided partials do not count toward quorum by themselves** — the consensus mirror-source rule requires the same K signer positions to approve both halves, so combine-proof only counts an index that has a valid signature on *both* sides. One-sided partials contribute only when another co-signer supplies the other-side signature at the same index.
 - `sign-proof` is idempotent: re-running with the same key replaces that signer's entry on the corresponding side.
@@ -859,32 +607,20 @@ Each co-signer sends their `*-partial.json` back to the coordinator.
 
 ### Step 3: Coordinator combines the partials
 
-```bash
-lumerad tx evmigration combine-proof \
-  alice-partial.json bob-partial.json \
-  --out tx.json
-```
+The coordinator combines reviewed partials through the manifest-pinned multisig helper; no abbreviated combine invocation is approved here.
 
 `combine-proof` validates cross-file consistency — it rejects the set if any two partials disagree on `chain_id`, `evm_chain_id`, `legacy_address`, `new_address`, `payload_hex`, `kind`, or the per-side `threshold` / `sig_format` / `sub_pub_keys`. It verifies every partial signature cryptographically on **both** sides, drops invalid entries with a stderr warning, then **intersects** the valid signer-index sets across the two sides and selects the first K indices present on BOTH. This is what satisfies the consensus mirror-source rule (`legacy_proof.signer_indices == new_proof.signer_indices`). A one-sided partial (e.g. co-signer Alice signed only the legacy side) does not count toward quorum unless another co-signer supplied a new-side signature at the same index. If the intersection has fewer than K entries, it errors with `need <K> valid partial signatures signed on BOTH sides at matching indices, have <N>` and writes nothing.
 
 ### Step 4: Broadcast the assembled transaction
 
-```bash
-lumerad tx evmigration submit-proof tx.json \
-  --chain-id <chain-id> \
-  --node <rpc-url> -y
-```
-
-Migration messages declare **zero signers** — authorization is embedded in `legacy_proof` and `new_proof`, fees are waived by the evmigration ante handler, and replay is prevented by the keeper's migration-record check. There is no `--from` and no envelope signature; `submit-proof` loads `tx.json`, runs `ValidateBasic`, simulates gas via the migration-specific estimator, builds an unsigned tx, and broadcasts. On success, verify the migration record:
+Submission uses the exact manifest-pinned helper and chain executable from the runbook, after the required stop proof and dry-run/review gates. Submit once.
 
-```bash
-lumerad query evmigration migration-record <multisig-legacy-address>
-```
+Migration messages declare **zero signers** — authorization is embedded in `legacy_proof` and `new_proof`, fees are waived by the evmigration ante handler, and replay is prevented by the keeper's migration-record check. There is no `--from` and no envelope signature. On success, verify the migration record with [Operator Runbook §7](operator-migration-runbook.md#7-retry-boundary-query-before-any-retry).
 
 ### Notes
 
 - **Legacy-side threshold and members** are defined by the on-chain `LegacyAminoPubKey` and read automatically; you don't pass them as flags. **New-side threshold and members** are supplied by `--new-sub-pub-keys` + `--new-threshold` because the destination multisig doesn't exist on-chain yet.
 - **Cold-wallet / nil-pubkey single-sig accounts**: if a *single-key* (non-multisig) legacy account has never signed a transaction, use `generate-proof-payload --legacy-key <local-keyring-key>` to seed the pubkey from a local key. This is distinct from the multisig flow — multisig accounts must have their multisig pubkey already populated on-chain.
 - **Non-EVM-addressable destination.** The new multisig bech32 can perform Cosmos-side operations (staking, supernode, IBC, authz) but cannot originate `MsgEthereumTx`. Operators who want EVM DeFi access for rewards should configure a separate single-EOA withdraw address via `MsgSetWithdrawAddress`.
-- **Supernode operators** have their own step-by-step walkthrough for both the single-sig automatic path and the multisig manual path — see [supernode-migration.md](supernode-migration.md).
+- **Supernode operators** must use the manual one-shot campaign path in [supernode-migration.md](supernode-migration.md); automatic startup broadcast is not approved by this release.
 - **After a successful migration** follow the same post-migration steps as for any other account (add the new Lumera EVM chain definition to Keplr, verify balances at the new address, etc.).
diff --git a/docs/evm-integration/user-guides/operator-migration-runbook.md b/docs/evm-integration/user-guides/operator-migration-runbook.md
index 878cbdc9..13545f7e 100644
--- a/docs/evm-integration/user-guides/operator-migration-runbook.md
+++ b/docs/evm-integration/user-guides/operator-migration-runbook.md
@@ -51,14 +51,21 @@ Identify `runAsUser`, command/args, PVC/config/secret mounts, base directory, an
 
 ## 2. Pin binary, home, and keyring provenance
 
-Use the exact release executables and explicit flags. The helpers resolve `--binary` once to an absolute canonical path, then print that path, the actual `version --long` version, SHA-256, and source before doing key work. They print keyring backend and keyring location separately, with each source. Independently verify all three executable records in the manifest: `artifacts.chain_executable`, `artifacts.supernode_executable`, and `artifacts.sncli_executable`, including each exact `release_path`, version, tag, commit, SHA-256, and source. For container procedures, also pull and inspect the exact `artifacts.container_image.artifact@artifacts.container_image.digest` from `artifacts.container_image.source`; a mutable tag alone is not approved.
+Use the exact release executables and explicit flags. The helpers resolve `--binary` once to an absolute canonical path, then print that path, the actual `version --long` version, SHA-256, and source before doing key work. They print keyring backend and keyring location separately, with each source. Independently verify all four executable records in the manifest: `artifacts.chain_executable`, `artifacts.supernode_executable`, `artifacts.sncli_executable`, and `artifacts.relayer_executable`, including each exact `release_path`, version, tag, commit, SHA-256, and source. Every `artifacts.bound_files` record also binds its exact runtime `release_path`; approval is deployment-specific, so those paths must be the paths this procedure actually executes. For container procedures, also pull and inspect the exact `artifacts.container_image.artifact@artifacts.container_image.digest` from `artifacts.container_image.source`; a mutable tag alone is not approved.
 
 ```bash
-LUMERAD=/absolute/path/to/approved/lumerad
+MANIFEST=/absolute/path/to/approved/compatibility-manifest.json
+LUMERAD=$(jq -er '.artifacts.chain_executable.release_path' "$MANIFEST")
+MIGRATE_VALIDATOR=$(jq -er '.artifacts.bound_files["scripts/migrate-validator.sh"].release_path' "$MANIFEST")
+test "${LUMERAD#/}" != "$LUMERAD" && test "${MIGRATE_VALIDATOR#/}" != "$MIGRATE_VALIDATOR"
+printf '%s  %s\n' \
+  "$(jq -er '.artifacts.chain_executable.sha256' "$MANIFEST")" "$LUMERAD" \
+  "$(jq -er '.artifacts.bound_files["scripts/migrate-validator.sh"].sha256' "$MANIFEST")" "$MIGRATE_VALIDATOR" \
+  | sha256sum -c -
 "$LUMERAD" version --long | tee "$EVIDENCE_DIR/lumerad-version.txt"
 sha256sum "$LUMERAD" | tee "$EVIDENCE_DIR/lumerad.sha256"
 
-sudo -u <service-user> ./scripts/migrate-validator.sh \
+sudo -u <service-user> "$MIGRATE_VALIDATOR" \
   <legacy-key-name> <destination-key-name> \
   --binary "$LUMERAD" \
   --home /absolute/lumera/home \
@@ -148,7 +155,7 @@ The irreversible boundary is the first live helper invocation. Choose the branch
 ### systemd / secured operator host
 
 ```bash
-sudo -u <service-user> ./scripts/migrate-validator.sh \
+sudo -u <service-user> "$MIGRATE_VALIDATOR" \
   <legacy-key-name> <destination-key-name> \
   --binary "$LUMERAD" \
   --home /absolute/lumera/home \
@@ -166,12 +173,22 @@ Do not apply the systemd command to a container deployment. Keep the original wo
 ```bash
 # The workload container remains stopped for both invocations.
 test "$(docker inspect -f '{{.State.Running}}' <stopped-container>)" = false
-APPROVED_IMAGE='<artifacts.container_image.artifact>@<artifacts.container_image.digest>'
+APPROVED_IMAGE="$(jq -er '.artifacts.container_image.artifact' "$MANIFEST")@$(jq -er '.artifacts.container_image.digest' "$MANIFEST")"
 SERVICE_UID_GID='<uid>:<gid>'
-MIGRATION_HELPER='<manifest-pinned-helper-release_path-in-image>'
-LUMERAD_IN_IMAGE='<artifacts.chain_executable.release_path-in-image>'
+MIGRATION_HELPER=$(jq -er '.artifacts.bound_files["scripts/migrate-validator.sh"].release_path' "$MANIFEST")
+LUMERAD_IN_IMAGE=$(jq -er '.artifacts.chain_executable.release_path' "$MANIFEST")
+MIGRATION_HELPER_SHA256=$(jq -er '.artifacts.bound_files["scripts/migrate-validator.sh"].sha256' "$MANIFEST")
+LUMERAD_SHA256=$(jq -er '.artifacts.chain_executable.sha256' "$MANIFEST")
 CONTAINER_HOME='<original-home-mount-destination-from-docker-inspect>'
 CONTAINER_KEYRING_DIR='<original-keyring-mount-destination-from-docker-inspect>'
+test "${MIGRATION_HELPER#/}" != "$MIGRATION_HELPER" && test "${LUMERAD_IN_IMAGE#/}" != "$LUMERAD_IN_IMAGE"
+
+# Verify the exact in-image paths before either invocation.
+docker run --rm --user "$SERVICE_UID_GID" \
+  --entrypoint /bin/sh \
+  -e MIGRATION_HELPER -e MIGRATION_HELPER_SHA256 -e LUMERAD_IN_IMAGE -e LUMERAD_SHA256 \
+  "$APPROVED_IMAGE" -ec \
+  'printf "%s  %s\n%s  %s\n" "$MIGRATION_HELPER_SHA256" "$MIGRATION_HELPER" "$LUMERAD_SHA256" "$LUMERAD_IN_IMAGE" | sha256sum -c -'
 
 run_migration() {
   docker run --rm -it --name evmigration-once \
@@ -198,7 +215,7 @@ run_migration
 
 ### Kubernetes one-shot pod
 
-Keep the StatefulSet at zero replicas. Apply a dedicated Pod using the workload's exact `serviceAccountName`, `runAsUser`/`runAsGroup`, PVC, config/keyring mount paths, manifest-pinned image digest, helper, binary, and trusted RPC. Do not mount a validator PVC read-write into any other pod concurrently.
+Keep the StatefulSet at zero replicas. Apply a dedicated Pod using the workload's exact `serviceAccountName`, `runAsUser`/`runAsGroup`, PVC, config/keyring mount paths, manifest-pinned image digest, helper, binary, and trusted RPC. Before applying, render each `<exact ...>` value below directly from the named manifest field; do not substitute a conventional `/release/...` path. The init container verifies those exact paths and the migration container executes the exact helper path. Do not mount a validator PVC read-write into any other pod concurrently.
 
 ```yaml
 apiVersion: v1
@@ -213,16 +230,27 @@ spec:
     runAsUser: <same-runAsUser>
     runAsGroup: <same-runAsGroup>
     fsGroup: <same-fsGroup>
+  initContainers:
+    - name: verify-release
+      image: <exact artifacts.container_image.artifact>@<exact artifacts.container_image.digest>
+      command: ["/bin/sh", "-ec"]
+      args:
+        - >-
+          printf '%s  %s\n%s  %s\n'
+          '<exact artifacts.bound_files["scripts/migrate-validator.sh"].sha256>'
+          '<exact artifacts.bound_files["scripts/migrate-validator.sh"].release_path>'
+          '<exact artifacts.chain_executable.sha256>'
+          '<exact artifacts.chain_executable.release_path>' | sha256sum -c -
   containers:
     - name: migrate
-      image: <registry>/<image>@sha256:<manifest-image-digest>
+      image: <exact artifacts.container_image.artifact>@<exact artifacts.container_image.digest>
       imagePullPolicy: IfNotPresent
-      command: ["/release/scripts/migrate-validator.sh"]
+      command: ['<exact artifacts.bound_files["scripts/migrate-validator.sh"].release_path>']
       args:
         - <legacy-key-name>
         - <destination-key-name>
         - --binary
-        - /release/bin/lumerad
+        - '<exact artifacts.chain_executable.release_path>'
         - --home
         - /mounted/lumera/home
         - --keyring-backend
@@ -313,12 +341,15 @@ This check has the same exact PR-2 compatibility dependency as destination prest
 
 ```bash
 umask 077
-SNCLI=/absolute/path/to/manifest-pinned/sncli
+SNCLI=$(jq -er '.artifacts.sncli_executable.release_path' "$MANIFEST")
+SNCLI_SHA256=$(jq -er '.artifacts.sncli_executable.sha256' "$MANIFEST")
 SNCLI_CONFIG=/absolute/supernode/basedir/sncli-config.toml
+test "${SNCLI#/}" != "$SNCLI"
 chmod 0600 "$SNCLI_CONFIG"
 # If passphrase_file is configured, its existing platform-secret mount must also be mode 0600:
 chmod 0600 /absolute/secret/mount/sncli-keyring-passphrase
-sha256sum "$SNCLI" | tee "$EVIDENCE_DIR/sncli.sha256"
+printf '%s  %s\n' "$SNCLI_SHA256" "$SNCLI" | sha256sum -c - \
+  | tee "$EVIDENCE_DIR/sncli.sha256"
 
 sudo -u <supernode-service-user> "$SNCLI" \
   --config "$SNCLI_CONFIG" \
diff --git a/docs/evm-integration/user-guides/relayer-migration.md b/docs/evm-integration/user-guides/relayer-migration.md
index a42f9d13..7729bf9e 100644
--- a/docs/evm-integration/user-guides/relayer-migration.md
+++ b/docs/evm-integration/user-guides/relayer-migration.md
@@ -5,12 +5,33 @@
 **Prerequisite reading**: [migration.md](migration.md) for the chain-level mechanics of legacy → EVM account migration
 
 > **Mandatory operations gate:** Use the [EVM Migration Operator Runbook](operator-migration-runbook.md) before this relayer procedure. The runbook adds release/binary/keyring provenance, mode-0600 config backup, no-echo destination staging, verified stop/restart alternatives, a one-broadcast rule, and secret-redacted evidence; this guide remains authoritative for Hermes' pinned HD path and key replacement.
+>
+> Discover the relayer service user's absolute Hermes base directory and use it for every read, backup, and mutation. Do not allow the invoking user's `~` or `$HOME` to select a relayer file. Populate and verify the exact manifest artifact before continuing:
+>
+> ```bash
+> MANIFEST=/absolute/path/to/approved/compatibility-manifest.json
+> HERMES=$(jq -er '.artifacts.relayer_executable.release_path' "$MANIFEST")
+> HERMES_SHA256=$(jq -er '.artifacts.relayer_executable.sha256' "$MANIFEST")
+> LUMERAD=$(jq -er '.artifacts.chain_executable.release_path' "$MANIFEST")
+> LUMERAD_SHA256=$(jq -er '.artifacts.chain_executable.sha256' "$MANIFEST")
+> MIGRATE_ACCOUNT=$(jq -er '.artifacts.bound_files["scripts/migrate-account.sh"].release_path' "$MANIFEST")
+> MIGRATE_ACCOUNT_SHA256=$(jq -er '.artifacts.bound_files["scripts/migrate-account.sh"].sha256' "$MANIFEST")
+> HERMES_HOME=/absolute/discovered/hermes/home
+> HERMES_CONFIG="$HERMES_HOME/config.toml"
+> test "${HERMES#/}" != "$HERMES" && test "${LUMERAD#/}" != "$LUMERAD"
+> test "${MIGRATE_ACCOUNT#/}" != "$MIGRATE_ACCOUNT" && test "${HERMES_HOME#/}" != "$HERMES_HOME"
+> printf '%s  %s\n%s  %s\n%s  %s\n' \
+>   "$HERMES_SHA256" "$HERMES" \
+>   "$LUMERAD_SHA256" "$LUMERAD" \
+>   "$MIGRATE_ACCOUNT_SHA256" "$MIGRATE_ACCOUNT" | sha256sum -c -
+> test -f "$HERMES_CONFIG"
+> ```
 
 ---
 
 ## Overview
 
-A Hermes relayer signs IBC packet/ack/timeout transactions on Lumera using a key in its own keyring (`~/.hermes/keys/<chain-id>/keyring-test/<key_name>.json`). If that account was created before the EVM upgrade it is a legacy `secp256k1` (coin-type 118) account, and it appears in `lumerad query evmigration legacy-accounts` until migrated.
+A Hermes relayer signs IBC packet/ack/timeout transactions on Lumera using a key under its discovered absolute `$HERMES_HOME/keys/<chain-id>/keyring-test/<key_name>.json`. If that account was created before the EVM upgrade it is a legacy `secp256k1` (coin-type 118) account.
 
 Migrating the relayer account is different from migrating a normal user account in one important way: **two independent tools must agree on the key.** `lumerad` performs the migration (it needs the destination key in its keyring to sign `MsgClaimLegacyAccount`), and **Hermes** must independently re-derive the *same* account from the *same* mnemonic so it can keep signing. Those two derivations only line up if you pin the HD path — see the gotcha below.
 
@@ -38,19 +59,11 @@ You must also tell Hermes the chain uses Ethereum-style keys, via `address_type`
 
 ## Prerequisites
 
-- Hermes ≥ 1.10 (verified on 1.13.2) with `ethermint` address-type support.
+- The manifest-pinned Hermes executable is ≥ 1.10 (verified on 1.13.2) with `ethermint` address-type support.
 - The relayer mnemonic, or the legacy relayer key present in a `lumerad` keyring (to sign the migration).
-- A `lumerad` binary that supports `eth_secp256k1` (the EVM-era Lumera binary).
-- The migration window open on-chain (`lumerad query evmigration params` → `enable_migration: true`).
+- The manifest-pinned chain executable supports `eth_secp256k1`, and its pinned query confirms the migration window is open.
 
-Confirm the current relayer account is legacy:
-
-```bash
-# from the Hermes host
-ADDR=$(hermes keys list --chain lumera-mainnet-1 | grep ' relayer ' | grep -oE 'lumera1[0-9a-z]+' | head -1)
-lumerad query evmigration migration-record "$ADDR" --output json   # record.new_address empty == not migrated
-lumerad query auth account "$ADDR" --output json                   # pub_key type secp256k1 == true legacy
-```
+Confirm the current relayer account is legacy using `$HERMES --config "$HERMES_CONFIG"` as the relayer service user and the runbook's manifest-pinned chain-query form. Do not use PATH lookup or a default Hermes config.
 
 ---
 
@@ -60,7 +73,7 @@ Throughout, `lumera-mainnet-1` is the chain id and `relayer` is the Hermes `key_
 
 ### Step 1 — Tell Hermes the Lumera chain uses Ethereum-style keys
 
-Edit `~/.hermes/config.toml` and add `address_type` to the **Lumera** `[[chains]]` block:
+Edit the discovered absolute `$HERMES_CONFIG` and add `address_type` to the **Lumera** `[[chains]]` block:
 
 ```toml
 [[chains]]
@@ -75,7 +88,7 @@ address_type = { derivation = 'ethermint', proto_type = { pk_type = '/cosmos.evm
 Validate:
 
 ```bash
-hermes config validate    # must print: SUCCESS configuration is valid
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" config validate
 ```
 
 ### Step 2 — Pre-stage the EVM destination key in lumerad
@@ -85,7 +98,7 @@ Use only the compatibility manifest's **verified, named, and hashed PR-2 no-echo
 Record only the public destination address:
 
 ```bash
-NEWADDR=$(sudo -u <relayer-service-user> /absolute/approved/lumerad keys show relayer-evm -a \
+NEWADDR=$(sudo -u <relayer-service-user> "$LUMERAD" keys show relayer-evm -a \
   --home /absolute/lumera/home \
   --keyring-backend <backend> \
   --keyring-dir /absolute/keyring/location)
@@ -101,14 +114,14 @@ Before the irreversible migration, confirm Hermes derives **exactly** `$NEWADDR`
 ```bash
 umask 077
 test "$(stat -c '%a' /run/secrets/relayer-evm.mnemonic)" = 600
-sudo -u <relayer-service-user> hermes keys add \
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --chain lumera-mainnet-1 --key-name relayer-evm-gate \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-sudo -u <relayer-service-user> hermes keys list --chain lumera-mainnet-1 | grep relayer-evm-gate
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 | grep relayer-evm-gate
 # the printed address MUST equal $NEWADDR. If it does not, STOP — do not migrate.
-sudo -u <relayer-service-user> hermes keys delete --chain lumera-mainnet-1 --key-name relayer-evm-gate
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys delete --chain lumera-mainnet-1 --key-name relayer-evm-gate
 ```
 
 If the addresses differ, re-check Step 1 (`address_type`) and the `--hd-path`. **Do not proceed past this gate on a mismatch** — you would migrate funds to an account Hermes cannot sign for.
@@ -118,9 +131,9 @@ If the addresses differ, re-check Step 1 (`address_type`) and the `--hd-path`. *
 Stop and prove stopped using the relayer's actual supervisor branch in the operator runbook. Then run the manifest-pinned helper as the discovered service user, with the exact approved binary/home/backend/keyring and trusted external RPC. The successful post-stop dry-run and destination-address match are mandatory; the following live command is run once only:
 
 ```bash
-sudo -u <relayer-service-user> /absolute/approved/scripts/migrate-account.sh \
+sudo -u <relayer-service-user> "$MIGRATE_ACCOUNT" \
   relayer-legacy relayer-evm \
-  --binary /absolute/approved/lumerad \
+  --binary "$LUMERAD" \
   --home /absolute/lumera/home \
   --keyring-backend <backend> \
   --keyring-dir /absolute/keyring/location \
@@ -131,8 +144,8 @@ sudo -u <relayer-service-user> /absolute/approved/scripts/migrate-account.sh \
 For Docker/Kubernetes, use the runbook's one-shot container/Pod form with these account-helper arguments; do not run this host/systemd form against container storage. `relayer-legacy` is the legacy relayer key in the same lumerad keyring. Migration is fee-free; the full balance moves to `$NEWADDR`. On a tx hash or ambiguous transport failure, apply the runbook's query-before-retry rule. Verify:
 
 ```bash
-lumerad query evmigration migration-record <legacy-addr> --output json | jq '.record.new_address'  # == $NEWADDR
-lumerad query bank balances "$NEWADDR" --output json | jq '.balances'                               # funds present
+"$LUMERAD" query evmigration migration-record <legacy-addr> --node <trusted-rpc> --output json | jq '.record.new_address'
+"$LUMERAD" query bank balances "$NEWADDR" --node <trusted-rpc> --output json | jq '.balances'
 ```
 
 ### Step 5 — Replace the Hermes relayer key with the EVM key
@@ -143,25 +156,25 @@ Back up and remove the old key, then import the EVM key under the relayer's `key
 umask 077
 RELAYER_BACKUP_DIR=/absolute/encrypted/operator-backup/relayer-$(date -u +%Y%m%dT%H%M%SZ)
 install -d -m 0700 "$RELAYER_BACKUP_DIR"
-install -m 0600 ~/.hermes/keys/lumera-mainnet-1/keyring-test/relayer.json \
+install -m 0600 "$HERMES_HOME/keys/lumera-mainnet-1/keyring-test/relayer.json" \
   "$RELAYER_BACKUP_DIR/relayer.json.bak"
 stat -c '%a %n' "$RELAYER_BACKUP_DIR/relayer.json.bak"  # must be 600
 
-sudo -u <relayer-service-user> hermes keys delete --chain lumera-mainnet-1 --key-name relayer
-sudo -u <relayer-service-user> hermes keys add \
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys delete --chain lumera-mainnet-1 --key-name relayer
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --chain lumera-mainnet-1 --key-name relayer \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-sudo -u <relayer-service-user> hermes keys list --chain lumera-mainnet-1 | grep ' relayer '   # MUST show $NEWADDR
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 | grep ' relayer '   # MUST show $NEWADDR
 ```
 
 ### Step 6 — Restart and verify
 
 ```bash
-# restart the hermes process/container so it loads the ethermint config + new key
-hermes keys balance --chain lumera-mainnet-1     # SUCCESS balance for key `relayer`: <amount> ulume
-hermes health-check                              # chain lumera-mainnet-1 is healthy
+# Restart through the discovered supervisor so Hermes loads the pinned config and new key.
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys balance --chain lumera-mainnet-1
+sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" health-check
 ```
 
 Watch the logs for a few packets to confirm it signs and broadcasts cleanly. IBC clients, connections, and channels are **not** owned by the relayer account, so they are unaffected by the key change — Hermes just needs a funded, signable account.
diff --git a/docs/evm-integration/user-guides/supernode-migration.md b/docs/evm-integration/user-guides/supernode-migration.md
index 8efbcdda..48945080 100644
--- a/docs/evm-integration/user-guides/supernode-migration.md
+++ b/docs/evm-integration/user-guides/supernode-migration.md
@@ -19,103 +19,25 @@
 
 ---
 
-## Overview
+## Approved campaign path
 
-When Lumera upgraded to an EVM-compatible chain, every supernode's legacy `secp256k1` key (coin-type 118) stopped matching the chain's new address derivation (`eth_secp256k1`, coin-type 60). The supernode daemon performs the migration automatically on startup once you add a new EVM key to its config.
+This release campaign is manual. The SuperNode daemon's automatic startup-broadcast path is **NOT APPROVED by this runbook or release**. It has not completed a separate, exact supervisor-specific rehearsal covering preflight, stopped-state proof, the startup irreversible boundary, and ambiguous-outcome query-before-restart behavior. Do not add `evm_key_name` and restart a legacy SuperNode in order to trigger a migration broadcast, and do not treat daemon idempotence as permission to retry startup after an ambiguous result.
 
-**This is the common case for virtually every supernode operator.** The rest of this document is the main walkthrough for that case.
+The approved single-signature procedure is:
 
-> If your supernode's on-chain operator account is a K-of-N multisig (rare, and only possible if you explicitly set one up), the daemon refuses to migrate and directs you to a manual `lumerad` CLI ceremony. See the [Multisig supernode accounts](#multisig-supernode-accounts) section at the end.
+1. Discover the SuperNode supervisor, service identity, absolute base/config/keyring paths, and exact manifest-pinned SuperNode, `sncli`, chain executable, and account-helper paths through the [Operator Runbook](operator-migration-runbook.md).
+2. Use the manifest-approved PR-2 no-echo operation to pre-stage and prove the coin-type-60 destination key. If that dependency is blocked, stop.
+3. Back up the discovered absolute SuperNode config, stop the workload through its discovered supervisor, and prove no duplicate process/container/pod can use the legacy key.
+4. Run the post-stop dry-run and the live `migrate-account.sh` one-shot exactly once through [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once). For a validator-bound SuperNode identity, follow [validator-migration.md](validator-migration.md) instead.
+5. Query the migration record before any retry. Only after the record proves the expected destination, update the discovered absolute `config.yml` to the destination identity/key as required by the release, restart exactly one supervised workload for local cleanup, and run the authenticated `sncli` acceptance check in [Operator Runbook §8](operator-migration-runbook.md#8-finalize-restart-and-verify).
 
-Migration is idempotent end-to-end: if anything fails mid-flight, restart the daemon and it resumes from whatever state the chain already has.
+A Portal/Keplr migration may also create the on-chain record, but service finalization still uses the same discovered absolute paths, stopped-state proof, destination-address match, supervised restart, and authenticated verification. It is not an automatic-broadcast branch.
 
----
-
-## Two ways to migrate (pick one)
-
-Both paths land in the same final state (new EVM key registered as supernode, legacy key deleted, `config.yml` updated). The operator steps are identical — what differs is whether the daemon initiates the on-chain migration or just finalizes one you already submitted.
-
-- **Path A — Supernode daemon migrates for you (recommended default).** You recover a new EVM key into the supernode keyring, add `evm_key_name` to `config.yml`, and restart. The daemon detects the legacy key, dual-signs with both keys, and broadcasts `MsgClaimLegacyAccount` itself. This is the flow the rest of this guide documents in steps 1–4.
-- **Path B — Migrate via Keplr + Portal first, then let the supernode finalize.** You use the Portal's standard [end-user migration](migration.md#method-1-portal--keplr-recommended) (browser + Keplr) to submit the migration transaction yourself. Then on the supernode host, you recover the same EVM key into the supernode's keyring, update `config.yml`, and restart. On startup the daemon sees the on-chain migration record, matches it against your configured `evm_key_name`, skips the broadcast, and performs only local cleanup.
-
-Path B is useful when you want to use Keplr's UX to see each step (the Portal shows balances, delegations, and a pre-migration checklist), when you need to migrate the account's balance urgently for non-supernode reasons, or when your node ops team and your wallet custody team are different people.
-
-> **Terminal alternative for Path B.** Do not use a shortened helper command from this guide. Follow the [Operator Runbook §6](operator-migration-runbook.md#6-re-run-dry-run-verify-destination-broadcast-once) non-validator branch with the manifest-pinned absolute `migrate-account.sh` and `lumerad` paths, discovered service identity, explicit home/keyring backend/keyring location/chain ID/trusted node, and the approved dry-run-before-live sequence. Then continue with Step B3 onward.
-
-**Why both paths work deterministically**: `supernode keys recover` derives keys at HD path `m/44'/60'/0'/0/0` using `eth_secp256k1`. Keplr uses the identical derivation for Lumera's EVM chain definition. Import the chosen destination mnemonic into both tools so they produce the same destination address. That mnemonic may be the legacy mnemonic or a different one.
-
-If you chose Path B, the steps below are the same but in Step 3 the logs will show a *skipped* broadcast (see the **Path B log variant** callout in that section).
-
----
-
-## Prerequisites
-
-Before starting:
-
-- Lumera chain is **EVM-enabled**. The supernode daemon verifies this at boot via `x/upgrade.ModuleVersions(evm)`. If the chain hasn't upgraded yet the daemon fatals with `connected Lumera chain does not have EVM support` — wait for the chain upgrade.
-- You hold the **mnemonic (seed phrase)** for the legacy supernode key.
-- You have access to the host running the supernode daemon and can edit `config.yml`.
-
----
-
-## Step 1 — Generate or recover the EVM destination key
-
-`supernode keys recover` must produce an `eth_secp256k1` key (coin-type 60) under a **new key name** distinct from the legacy key. **Required PR-2 compatibility dependency:** use the release's approved no-echo destination-prestage operation named and hashed in the compatibility manifest. It must read the mnemonic from a hidden TTY or protected input descriptor, never from argv. PR-3 intentionally does not invent a command for an unfinished PR-2 interface. If the manifest reports this dependency as blocked, stop; do not use the legacy `--mnemonic "..."` argv form.
-
-The approved pre-stage operation prints the new EVM address. Verify the resulting public key record using the manifest-pinned absolute `artifacts.supernode_executable.release_path`, the discovered SuperNode service identity/base directory, and the exact keyring backend/location from the operator runbook. Do not copy a bare `supernode keys list` shortcut that falls back to the interactive user's config or keyring.
-
-## Step 2 — Add `evm_key_name` to `config.yml`
-
-Edit `config.yml` (inside your supernode base directory) and add the `evm_key_name` field under `supernode:` alongside the existing `key_name`:
+## SuperNode-specific configuration contract
 
-```yaml
-supernode:
-  key_name: supernode-legacy       # existing legacy key (unchanged)
-  evm_key_name: supernode-evm      # new — must match the name you chose in step 1
-  identity: "lumera1...legacyaddr" # existing legacy address — daemon will rewrite on migration
-  # ...
-```
-
-Keep `key_name` and `identity` as-is — the daemon rewrites both after migration succeeds.
-
-## Step 3 — Restart the supernode
-
-The daemon detects the legacy key + `evm_key_name` on boot and runs the migration automatically. Watch the logs:
-
-```text
-INFO  EVM module detected on chain
-WARN  Legacy secp256k1 key detected — EVM account migration required
-INFO  Migration estimate  {"would_succeed": true, "is_validator": false, "is_multisig": false, ...}
-INFO  Migration tx passed CheckTx, waiting for block confirmation  {"tx_hash": "..."}
-INFO  Migration tx confirmed in block
-INFO  New address confirmed as registered supernode
-INFO  EVM migration complete — legacy key removed, config updated
-```
-
-On success, the daemon has:
-
-- Broadcast `MsgClaimLegacyAccount` (or `MsgMigrateValidator` if you're also a validator operator) with both signatures embedded.
-- Waited for block inclusion.
-- Deleted the old legacy key from the keyring.
-- Rewritten `config.yml`: `key_name: supernode-evm`, `identity: lumera1...newEVMaddr`, `evm_key_name` removed.
-
-From here on, the supernode runs on the EVM key with no further intervention.
-
-### Path B log variant — already migrated via Keplr
+The destination key must be `eth_secp256k1` at coin type 60 under a new name. Preserve the legacy `key_name` and `identity` until the one-shot migration is proven on-chain. After proof, apply the release-matched local finalization to the discovered absolute `config.yml`; never edit `~/.supernode/config.yml` under the interactive user or use a bare SuperNode key command.
 
-If you chose Path B and already submitted the migration via the Portal + Keplr flow, the restart supernode logs look like this instead:
-
-```text
-INFO  EVM module detected on chain
-WARN  Legacy secp256k1 key detected — EVM account migration required
-INFO  Account already migrated on-chain, skipping broadcast
-INFO  New address confirmed as registered supernode
-INFO  EVM migration complete — legacy key removed, config updated
-```
-
-The daemon queries `MigrationRecord(legacyAddr)`, sees that the on-chain record's `new_address` matches the address derived from your local `evm_key_name`, sets the internal `alreadyMigrated=true` flag, and skips the broadcast branch. The rest of the cleanup (delete legacy key, rewrite `config.yml`) runs identically to Path A.
-
-If the logs show `migration record exists on-chain but new address mismatch`, the EVM key you recovered into the supernode keyring isn't the one Keplr used during the Portal flow — either use the same mnemonic (the one that signed in the Portal), or investigate whether two different mnemonics got mixed up.
+Expected cleanup logs include an existing migration record, a matching destination address, and local configuration/key cleanup. Any destination mismatch is a hard stop: recover the exact key that controls the record's `new_address` or escalate; never broadcast again.
 
 ## Step 4 — Verify
 
@@ -137,92 +59,16 @@ sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyrin
 Finally, confirm `config.yml` reflects the switch:
 
 ```bash
-grep -E "key_name|identity|evm_key_name" ~/.supernode/config.yml
+grep -E "key_name|identity|evm_key_name" /absolute/discovered/supernode/config.yml
 ```
 
 You should see `key_name: <evm-key-name>`, `identity: <new-evm-address>`, and no `evm_key_name` line.
 
 ---
 
-## Path B — Migrating via Portal + Keplr first
-
-Use this section if you chose Path B from the ["Two ways to migrate"](#two-ways-to-migrate-pick-one) choice above. Follow the steps in order — don't interleave with Path A steps.
-
-### Before you start
-
-- Import the chosen destination mnemonic in Keplr and on the supernode host so both control the destination recorded by the migration. It may be the legacy mnemonic or a different mnemonic.
-- Decide *when* you'll run each step. A safe order is: stop the supernode → migrate in Keplr → recover the EVM key → edit config → restart. Leaving the supernode running between the Portal migration and the final restart is not harmful (the legacy account no longer exists on-chain, so the supernode's outgoing txs will fail fast), but it produces alarming-looking errors in the logs until you restart.
-
-### Step B1 — Stop the supernode
-
-```bash
-systemctl stop supernode   # or whatever init system you use
-```
-
-Stopping avoids log noise and ensures no inflight txs from the legacy key race with the migration.
-
-### Step B2 — Migrate the account via the Portal (Keplr)
-
-Follow the standard end-user migration flow in [migration.md → Method 1: Portal + Keplr](migration.md#method-1-portal--keplr-recommended). The supernode account behaves like any other Keplr account in this flow — there's nothing supernode-specific to do in the browser.
-
-Quick summary of what you'll do:
-
-1. Open the Lumera Portal's **Claim** page.
-2. Connect Keplr with the mnemonic that currently controls the legacy supernode account.
-3. The portal auto-detects the legacy account, shows your balance/delegations/supernode status, and offers a "Ready to Migrate" wizard.
-4. Click through Review → Sign & Confirm → Submit. Keplr will pop up twice to sign the legacy proof (ADR-036) and the new proof (Ethereum `personal_sign`).
-5. The portal confirms the transaction and shows the migration record with `new_address`.
-
-After the Portal shows success, verify the on-chain record on the host (or on the Portal's success screen):
-
-```bash
-sudo -u <supernode-service-user> "$LUMERAD" query --home "$LUMERA_HOME" --keyring-backend "$KEYRING_BACKEND" --keyring-dir "$KEYRING_DIR" --chain-id "$CHAIN_ID" --node "$TRUSTED_RPC" evmigration migration-record <legacy-address>
-```
-
-Note the `new_address` — you'll verify that it matches what the supernode derives locally in Step B5.
-
-### Step B3 — Recover the new EVM key into the supernode keyring
-
-Exactly the same operation as Path A's Step 1. **Use the same mnemonic you used in Keplr** — this is the critical piece that makes Path B work. Run the release-manifest-approved PR-2 no-echo destination-prestage operation, then verify the public record through the same manifest-pinned absolute SuperNode executable, service identity/base directory, and explicit keyring context required there; do not use a bare key-list shortcut.
-
-### Step B4 — Add `evm_key_name` to `config.yml`
-
-Exactly the same operation as Path A's Step 2:
-
-```yaml
-supernode:
-  key_name: supernode-legacy       # existing legacy key (unchanged)
-  evm_key_name: supernode-evm      # must match the name you chose in Step B3
-  identity: "lumera1...legacyaddr" # existing legacy address — daemon will rewrite on restart
-  # ...
-```
-
-### Step B5 — Restart the supernode (local cleanup only)
-
-```bash
-systemctl start supernode
-```
-
-On startup the daemon:
-
-1. Detects the legacy key in the keyring (`is_legacy_key=true`).
-2. Queries `MigrationRecord(legacyAddr)` — finds the record you submitted via Keplr.
-3. Compares the record's `new_address` to the address derived from your locally-imported `evm_key_name` — they match (same mnemonic, same HD path, same algorithm).
-4. Sets `alreadyMigrated=true` and **skips the broadcast step entirely**.
-5. Performs only local cleanup: rewrites `config.yml` (`key_name` → evm key name, `identity` → new address, removes `evm_key_name`), deletes the old legacy key from the keyring.
-
-Expected logs — see the [Path B log variant](#path-b-log-variant--already-migrated-via-keplr) callout in Step 3 for the exact sequence. The key line is `INFO  Account already migrated on-chain, skipping broadcast`.
-
-### Step B6 — Verify
-
-Same as Path A's [Step 4 — Verify](#step-4--verify). Three queries — migration record, supernode registration at the new address, and `config.yml` state — all should reflect the new EVM address.
-
-### Path B gotchas
+## Portal-created migration record
 
-- **Different mnemonic on supernode host**: if the mnemonic you recover with `supernode keys recover` is *not* the one you used in Keplr, the derived bech32 addresses differ, and the daemon logs `migration record exists on-chain but new address mismatch` and exits. Recover with the Keplr mnemonic and retry.
-- **Picked the wrong Keplr account**: if Keplr held multiple accounts and you migrated the wrong one, the on-chain migration record points to the wrong legacy address. Check the Portal's success page for the legacy address it migrated from — it must match your supernode's current `identity`.
-- **Supernode never stopped**: if the supernode kept running between Step B2 and Step B5, its outbound txs will have been erroring with "account not found" for the duration. This is cosmetic — the final restart clears the state. But stop-first is cleaner.
-- **Multisig legacy account**: Path B does not apply to multisig supernode accounts — Keplr can't drive a K-of-N ceremony. See the [Multisig supernode accounts](#multisig-supernode-accounts) section.
+If Portal/Keplr creates the migration record, use [migration.md → Method 1](migration.md#method-1-portal--keplr-recommended) for the wallet flow, but use this guide's approved campaign path for the service. Prove the SuperNode stopped through its discovered supervisor, verify the record with the manifest-pinned chain executable, pre-stage the exact destination key through PR-2, and confirm its address matches the record. Then apply local finalization to the discovered absolute config and restart through the supervisor **only for cleanup**. A mismatch or ambiguous record is a hard stop.
 
 ---
 
@@ -230,7 +76,7 @@ Same as Path A's [Step 4 — Verify](#step-4--verify). Three queries — migrati
 
 ### `evm_key_name "<name>" is not an eth_secp256k1 key`
 
-You created or recovered the EVM-named key with the wrong algorithm. Delete it and re-run `supernode keys recover` (which always produces `eth_secp256k1`).
+The destination key has the wrong algorithm. Remove it only through the manifest-approved key operation and repeat the approved PR-2 no-echo prestage with `eth_secp256k1`; do not use a bare recovery shortcut.
 
 ### `simulation failed: rpc error: ... invalid length: tx parse error`
 
@@ -261,7 +107,7 @@ No. The migration re-keys the on-chain record: your supernode registration, evid
 No — a single `MsgMigrateValidator` re-keys both the validator operator record and the supernode record bound to it. See [validator-migration.md](validator-migration.md) for the validator-specific walkthrough (including the maintenance window and the `max_validator_delegations` check); the supernode side happens as a side-effect of that tx.
 
 **Q: Can I roll back if the migration fails mid-flight?**
-No rollback is needed — the daemon is idempotent. If the broadcast fails, restart; if the broadcast succeeded but local cleanup failed, restart. Each restart resumes from the current chain state.
+No. Before broadcast, correct inputs and repeat the dry-run. After a tx hash or ambiguous failure, query the tx and migration record and escalate before any retry. Restart only after the record proves the expected destination, and only for supervised local cleanup; never restart to retry automatic broadcast.
 
 ---
 
diff --git a/docs/evm-integration/user-guides/validator-migration.md b/docs/evm-integration/user-guides/validator-migration.md
index 923b442d..b4e540ae 100644
--- a/docs/evm-integration/user-guides/validator-migration.md
+++ b/docs/evm-integration/user-guides/validator-migration.md
@@ -297,9 +297,9 @@ After the validator migration and restart, also restart the supernode so it pick
 
 Restart the SuperNode through its independently discovered supervisor/workload identity and prove exactly one supervised instance is running, following the operator runbook's matching systemd, Docker, or Kubernetes branch.
 
-See [supernode-migration.md](supernode-migration.md) for the supernode daemon's config-update behavior — it detects the on-chain migration record on the next startup and rewrites `config.yml` automatically.
+See [supernode-migration.md](supernode-migration.md) for the approved manual campaign and supervised local-finalization behavior after the on-chain migration record is verified.
 
-If your validator and supernode are **different entities** (separate addresses), migrate them independently — the supernode uses `MsgClaimLegacyAccount` via its own flow (or the supernode daemon's automatic startup migration).
+If your validator and supernode are **different entities** (separate addresses), migrate them independently. The SuperNode uses the manual one-shot `MsgClaimLegacyAccount` campaign; daemon automatic startup broadcast is not approved by this release.
 
 ---
 
@@ -458,6 +458,6 @@ Migrate the validator first; `MsgMigrateValidator` handles the supernode side as
 
 - [migration.md](migration.md) — chain-level end-user migration guide (Portal + Keplr, shell scripts, raw CLI)
 - [migration-scripts.md](migration-scripts.md) — reference for `migrate-validator.sh` and `migrate-account.sh` (flags, exit codes, troubleshooting, non-interactive / CI usage)
-- [supernode-migration.md](supernode-migration.md) — supernode operator migration (automatic single-sig path, manual multisig path)
+- [supernode-migration.md](supernode-migration.md) — approved manual SuperNode campaign and multisig semantics; automatic startup broadcast is blocked
 - [legacy-migration.md](../evmigration/legacy-migration.md) — `x/evmigration` module architecture, proto shapes, keeper logic, and the full reference for the offline proof flow
 - [node-evm-config-guide.md](node-evm-config-guide.md) — post-upgrade `app.toml` / RPC configuration for full nodes and validators

From d3dd385f5ef20215b2ee557a08ad17240f1e1c45 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 05:00:36 +0000
Subject: [PATCH 04/11] docs(evmigration): require absolute manifest runtime
 paths

---
 .../compatibility-manifest.schema.json        |   9 +-
 .../compatibility-manifest.template.json      |  32 ++--
 tests/scripts/compatibility-manifest.bats     |   7 +
 .../compatibility_manifest_schema_test.py     | 148 ++++++++++++++++++
 4 files changed, 178 insertions(+), 18 deletions(-)
 create mode 100644 tests/scripts/compatibility-manifest.bats
 create mode 100644 tests/scripts/compatibility_manifest_schema_test.py

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
index 8c131e52..c29e80a7 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -217,6 +217,11 @@
     }
   ],
   "$defs": {
+    "absolute_path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^/"
+    },
     "non_placeholder": {
       "type": "string",
       "minLength": 3,
@@ -235,7 +240,7 @@
       "additionalProperties": false,
       "required": ["release_path", "sha256", "source"],
       "properties": {
-        "release_path": { "type": "string", "minLength": 1 },
+        "release_path": { "$ref": "#/$defs/absolute_path" },
         "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
         "source": { "type": "string", "minLength": 1 }
       }
@@ -254,7 +259,7 @@
       "required": ["name", "release_path", "version", "tag", "commit", "sha256", "source"],
       "properties": {
         "name": { "type": "string", "minLength": 1 },
-        "release_path": { "type": "string", "minLength": 1 },
+        "release_path": { "$ref": "#/$defs/absolute_path" },
         "version": { "type": "string", "minLength": 1 },
         "tag": { "type": "string", "minLength": 1 },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
index 16402ba4..484fabb0 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -14,7 +14,7 @@
   "artifacts": {
     "chain_executable": {
       "name": "lumerad",
-      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_LUMERAD",
+      "release_path": "/REPLACE_WITH_TARBALL_PATH_TO_LUMERAD",
       "version": "REPLACE_WITH_LUMERAD_VERSION_LONG",
       "tag": "REPLACE_WITH_CHAIN_RELEASE_TAG",
       "commit": "0000000000000000000000000000000000000000",
@@ -23,7 +23,7 @@
     },
     "supernode_executable": {
       "name": "supernode",
-      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_SUPERNODE",
+      "release_path": "/REPLACE_WITH_TARBALL_PATH_TO_SUPERNODE",
       "version": "REPLACE_WITH_SUPERNODE_VERSION",
       "tag": "REPLACE_WITH_SUPERNODE_RELEASE_TAG",
       "commit": "0000000000000000000000000000000000000000",
@@ -32,7 +32,7 @@
     },
     "sncli_executable": {
       "name": "sncli",
-      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_SNCLI",
+      "release_path": "/REPLACE_WITH_TARBALL_PATH_TO_SNCLI",
       "version": "REPLACE_WITH_SNCLI_VERSION",
       "tag": "REPLACE_WITH_SNCLI_RELEASE_TAG",
       "commit": "0000000000000000000000000000000000000000",
@@ -41,7 +41,7 @@
     },
     "relayer_executable": {
       "name": "hermes",
-      "release_path": "REPLACE_WITH_TARBALL_PATH_TO_HERMES",
+      "release_path": "/REPLACE_WITH_TARBALL_PATH_TO_HERMES",
       "version": "REPLACE_WITH_HERMES_VERSION",
       "tag": "REPLACE_WITH_HERMES_RELEASE_TAG",
       "commit": "0000000000000000000000000000000000000000",
@@ -55,62 +55,62 @@
     },
     "bound_files": {
       "scripts/evmigration-common.sh": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/evmigration-common.sh",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_scripts/evmigration-common.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/evmigration-common.sh"
       },
       "scripts/migrate-account.sh": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-account.sh",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-account.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-account.sh"
       },
       "scripts/migrate-validator.sh": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-validator.sh",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-validator.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-validator.sh"
       },
       "scripts/migrate-multisig.sh": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-multisig.sh",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-multisig.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-multisig.sh"
       },
       "scripts/migrate-batch.sh": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-batch.sh",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_scripts/migrate-batch.sh",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#scripts/migrate-batch.sh"
       },
       "docs/evm-integration/user-guides/operator-migration-runbook.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/operator-migration-runbook.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/operator-migration-runbook.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/operator-migration-runbook.md"
       },
       "docs/evm-integration/user-guides/migration.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration.md"
       },
       "docs/evm-integration/user-guides/migration-scripts.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration-scripts.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/migration-scripts.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/migration-scripts.md"
       },
       "docs/evm-integration/user-guides/validator-migration.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/validator-migration.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/validator-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/validator-migration.md"
       },
       "docs/evm-integration/user-guides/supernode-migration.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/supernode-migration.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/supernode-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/supernode-migration.md"
       },
       "docs/evm-integration/user-guides/relayer-migration.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/relayer-migration.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/user-guides/relayer-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/user-guides/relayer-migration.md"
       },
       "docs/evm-integration/evmigration/legacy-migration.md": {
-        "release_path": "REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/evmigration/legacy-migration.md",
+        "release_path": "/REPLACE_WITH_RUNTIME_PATH_TO_docs/evm-integration/evmigration/legacy-migration.md",
         "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
         "source": "REPLACE_WITH_CHAIN_RELEASE_ASSET#docs/evm-integration/evmigration/legacy-migration.md"
       }
diff --git a/tests/scripts/compatibility-manifest.bats b/tests/scripts/compatibility-manifest.bats
new file mode 100644
index 00000000..17e5ed53
--- /dev/null
+++ b/tests/scripts/compatibility-manifest.bats
@@ -0,0 +1,7 @@
+#!/usr/bin/env bats
+
+@test "compatibility manifest schema rejects unsafe runtime paths" {
+  run python3 tests/scripts/compatibility_manifest_schema_test.py
+
+  [ "$status" -eq 0 ]
+}
diff --git a/tests/scripts/compatibility_manifest_schema_test.py b/tests/scripts/compatibility_manifest_schema_test.py
new file mode 100644
index 00000000..b7a90644
--- /dev/null
+++ b/tests/scripts/compatibility_manifest_schema_test.py
@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Adversarial validation for the EVM migration compatibility manifest."""
+
+import copy
+import json
+import unittest
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACT_DIR = REPO_ROOT / "docs/evm-integration/operator-artifacts"
+SCHEMA_PATH = ARTIFACT_DIR / "compatibility-manifest.schema.json"
+TEMPLATE_PATH = ARTIFACT_DIR / "compatibility-manifest.template.json"
+
+
+def load_json(path: Path):
+    with path.open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def approved_manifest(template):
+    manifest = copy.deepcopy(template)
+    manifest.pop("_signing_blocker", None)
+
+    manifest["release"] = {
+        "tag": "v1.20.0",
+        "commit": "1" * 40,
+        "release_url": "https://example.com/releases/v1.20.0",
+    }
+    manifest["chain"] = {
+        "chain_id": "lumera-mainnet-1",
+        "evm_chain_id": 1234,
+        "minimum_upgrade": "v1.20.0",
+    }
+
+    for name, executable in manifest["artifacts"].items():
+        if not name.endswith("_executable"):
+            continue
+        executable.update(
+            release_path=f"/opt/lumera/bin/{executable['name']}",
+            version="1.20.0",
+            tag="v1.20.0",
+            commit="2" * 40,
+            sha256="3" * 64,
+            source=f"https://example.com/releases/{executable['name']}",
+        )
+
+    manifest["artifacts"]["container_image"] = {
+        "artifact": "registry.example.com/lumera/supernode:v1.20.0",
+        "digest": "sha256:" + "4" * 64,
+        "source": "https://registry.example.com/lumera/supernode",
+    }
+    for relative_name, bound_file in manifest["artifacts"]["bound_files"].items():
+        bound_file.update(
+            release_path=f"/opt/lumera/release/{relative_name}",
+            sha256="5" * 64,
+            source=f"https://example.com/releases/v1.20.0#{relative_name}",
+        )
+
+    manifest["operator_contracts"]["destination_prestage_no_echo"] = {
+        "status": "verified",
+        "implementation": {
+            "name": "destination-prestage",
+            "tag": "v1.20.0",
+            "commit": "6" * 40,
+            "sha256": "7" * 64,
+            "source": "https://example.com/releases/destination-prestage",
+            "no_echo_contract": "hidden-tty-or-protected-fd;never-argv;never-echo;no-xtrace",
+        },
+    }
+    for check in manifest["validation"].values():
+        check.update(status="pass", evidence="verified release evidence")
+
+    manifest["approval"].update(status="approved", release_owner_approved=True)
+    manifest["approval"]["detached_signature"].update(
+        certificate_identity="release-owner@example.com",
+        certificate_oidc_issuer="https://issuer.example.com",
+    )
+    manifest["_verification"] = ["All release-owner verification steps completed."]
+    return manifest
+
+
+class CompatibilityManifestSchemaTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.schema = load_json(SCHEMA_PATH)
+        cls.template = load_json(TEMPLATE_PATH)
+        Draft202012Validator.check_schema(cls.schema)
+        cls.validator = Draft202012Validator(cls.schema)
+        cls.approved = approved_manifest(cls.template)
+
+    def assert_invalid(self, manifest):
+        with self.assertRaises(ValidationError):
+            self.validator.validate(manifest)
+
+    def test_blocked_template_is_schema_valid(self):
+        self.validator.validate(self.template)
+
+    def test_approved_absolute_runtime_paths_are_valid(self):
+        self.validator.validate(self.approved)
+
+    def test_unresolved_template_cannot_be_approved(self):
+        unsafe = copy.deepcopy(self.template)
+        unsafe["approval"]["status"] = "approved"
+        self.assert_invalid(unsafe)
+
+    def test_blocked_relative_runtime_paths_are_rejected(self):
+        relative_executable = copy.deepcopy(self.template)
+        relative_executable["artifacts"]["chain_executable"]["release_path"] = (
+            "bin/lumerad"
+        )
+        self.assert_invalid(relative_executable)
+
+        relative_file = copy.deepcopy(self.template)
+        relative_file["artifacts"]["bound_files"]["scripts/migrate-validator.sh"][
+            "release_path"
+        ] = "scripts/migrate-validator.sh"
+        self.assert_invalid(relative_file)
+
+    def test_approved_relative_executable_release_path_is_rejected(self):
+        unsafe = copy.deepcopy(self.approved)
+        unsafe["artifacts"]["chain_executable"]["release_path"] = "bin/lumerad"
+        self.assert_invalid(unsafe)
+
+    def test_approved_relative_bound_file_release_path_is_rejected(self):
+        unsafe = copy.deepcopy(self.approved)
+        unsafe["artifacts"]["bound_files"]["scripts/migrate-validator.sh"][
+            "release_path"
+        ] = "scripts/migrate-validator.sh"
+        self.assert_invalid(unsafe)
+
+    def test_url_sources_are_not_constrained_as_runtime_paths(self):
+        manifest = copy.deepcopy(self.approved)
+        manifest["release"]["release_url"] = "https://example.com/release"
+        manifest["artifacts"]["chain_executable"]["source"] = (
+            "https://example.com/releases/lumerad"
+        )
+        manifest["artifacts"]["bound_files"]["scripts/migrate-validator.sh"][
+            "source"
+        ] = "https://example.com/releases/scripts#migrate-validator.sh"
+        self.validator.validate(manifest)
+
+
+if __name__ == "__main__":
+    unittest.main()

From fb672500a633b0793d810c43d6e2aa4af850844e Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 10:16:41 +0000
Subject: [PATCH 05/11] fix(devnet): resolve upgrade compose path from script

---
 devnet/scripts/submit-upgrade-proposal.sh     |  4 +++-
 .../common/upgrade_proposal_script_test.go    | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/devnet/scripts/submit-upgrade-proposal.sh b/devnet/scripts/submit-upgrade-proposal.sh
index 71b7819d..44ded799 100755
--- a/devnet/scripts/submit-upgrade-proposal.sh
+++ b/devnet/scripts/submit-upgrade-proposal.sh
@@ -13,13 +13,15 @@
 # Configuration
 VERSION="$1"
 UPGRADE_HEIGHT="$2"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEVNET_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 CHAIN_ID="lumera-devnet-1"
 SERVICE="supernova_validator_1" # primary validator
 LUMERA_SHARED="/tmp/${CHAIN_ID}/shared"
 KEYRING="test"
 HOST_PROPOSAL_FILE="${LUMERA_SHARED}/upgrade_${VERSION}.json"
 CONTAINER_PROPOSAL_FILE="/shared/upgrade_${VERSION}.json"
-COMPOSE_FILE="../docker-compose.yml"
+COMPOSE_FILE="${DEVNET_ROOT}/docker-compose.yml"
 STATUS_DIR="${LUMERA_SHARED}/status"
 ACCOUNT_REGISTRY_FILE="${STATUS_DIR}/${SERVICE}/accounts.json"
 
diff --git a/devnet/tests/common/upgrade_proposal_script_test.go b/devnet/tests/common/upgrade_proposal_script_test.go
index 7fd93a27..efdff7aa 100644
--- a/devnet/tests/common/upgrade_proposal_script_test.go
+++ b/devnet/tests/common/upgrade_proposal_script_test.go
@@ -3,6 +3,7 @@ package common
 import (
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -20,6 +21,24 @@ func runUpgradeProposalScriptScenario(t *testing.T, testScript string) {
 	}
 }
 
+func TestUpgradeProposalComposePathIsIndependentOfWorkingDirectory(t *testing.T) {
+	scriptPath, err := filepath.Abs("../../scripts/submit-upgrade-proposal.sh")
+	if err != nil {
+		t.Fatalf("resolve proposal script path: %v", err)
+	}
+	expected := filepath.Clean(filepath.Join(filepath.Dir(scriptPath), "..", "docker-compose.yml"))
+
+	cmd := exec.Command("bash", "-c", `source "$1"; printf '%s\n' "$COMPOSE_FILE"`, "upgrade-proposal-path-test", scriptPath)
+	cmd.Dir = t.TempDir()
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("source proposal script: %v\n%s", err, out)
+	}
+	if got := strings.TrimSpace(string(out)); got != expected {
+		t.Fatalf("compose path must be script-relative: got %q, want %q", got, expected)
+	}
+}
+
 func TestUpgradeProposalRestoresKeyForPersistedMigratedAddress(t *testing.T) {
 	const testScript = `
 source "$1"

From 89b8285c4788412d61d5c2911ecc9d8b934c89a0 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 10:18:58 +0000
Subject: [PATCH 06/11] fix(devnet): resolve vote compose path from script

---
 devnet/scripts/vote-all.sh                  |  4 ++-
 devnet/tests/common/vote_all_script_test.go | 32 +++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 devnet/tests/common/vote_all_script_test.go

diff --git a/devnet/scripts/vote-all.sh b/devnet/scripts/vote-all.sh
index d325aa14..c428c382 100755
--- a/devnet/scripts/vote-all.sh
+++ b/devnet/scripts/vote-all.sh
@@ -7,11 +7,13 @@ if [ -z "$1" ]; then
 fi
 
 # Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEVNET_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 CHAIN_ID="lumera-devnet-1"
 KEYRING_BACKEND="test"
 PROPOSAL_ID="$1"
 SERVICE_NAME="supernova_validator_1"
-COMPOSE_FILE="../docker-compose.yml"
+COMPOSE_FILE="${DEVNET_ROOT}/docker-compose.yml"
 FEES="5000ulume"
 # Gas configuration — use a fixed gas amount by default. `--gas auto` simulates
 # a gov vote at ~57.9k and even with a 1.3x bump lands right at the real usage
diff --git a/devnet/tests/common/vote_all_script_test.go b/devnet/tests/common/vote_all_script_test.go
new file mode 100644
index 00000000..b8ac5a87
--- /dev/null
+++ b/devnet/tests/common/vote_all_script_test.go
@@ -0,0 +1,32 @@
+package common
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestVoteAllComposePathIsScriptRelative(t *testing.T) {
+	scriptPath, err := filepath.Abs("../../scripts/vote-all.sh")
+	if err != nil {
+		t.Fatalf("resolve vote script path: %v", err)
+	}
+	contents, err := os.ReadFile(scriptPath)
+	if err != nil {
+		t.Fatalf("read vote script: %v", err)
+	}
+	script := string(contents)
+	for _, required := range []string{
+		`SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"`,
+		`DEVNET_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"`,
+		`COMPOSE_FILE="${DEVNET_ROOT}/docker-compose.yml"`,
+	} {
+		if !strings.Contains(script, required) {
+			t.Fatalf("vote script must contain %q", required)
+		}
+	}
+	if strings.Contains(script, `COMPOSE_FILE="../docker-compose.yml"`) {
+		t.Fatal("vote script must not resolve compose path from caller working directory")
+	}
+}

From ba01c55955e5322172c40cbc8571ca20ad9c304e Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 14:49:10 +0000
Subject: [PATCH 07/11] fix(devnet): restrict mnemonic registry permissions

---
 devnet/scripts/account-registry.sh            |  7 ++--
 .../account_registry_permissions_test.go      | 35 +++++++++++++++++++
 2 files changed, 39 insertions(+), 3 deletions(-)
 create mode 100644 devnet/tests/common/account_registry_permissions_test.go

diff --git a/devnet/scripts/account-registry.sh b/devnet/scripts/account-registry.sh
index 5104c0fb..f6b26ae5 100644
--- a/devnet/scripts/account-registry.sh
+++ b/devnet/scripts/account-registry.sh
@@ -5,6 +5,7 @@
 
 ACCOUNTS_DISPLAY_DENOM_DEFAULT="${ACCOUNTS_DISPLAY_DENOM_DEFAULT:-lume}"
 ACCOUNTS_DISPLAY_EXPONENT_DEFAULT="${ACCOUNTS_DISPLAY_EXPONENT_DEFAULT:-6}"
+ACCOUNTS_FILE_MODE="${ACCOUNTS_FILE_MODE:-600}"
 
 accounts_registry_init() {
 	local node_status_dir="$1"
@@ -28,7 +29,7 @@ ensure_accounts_registry() {
 	if [[ ! -f "${ACCOUNTS_FILE}" ]]; then
 		printf '[]\n' >"${ACCOUNTS_FILE}"
 	fi
-	chmod 644 "${ACCOUNTS_FILE}"
+	chmod "${ACCOUNTS_FILE_MODE}" "${ACCOUNTS_FILE}"
 }
 
 accounts_registry_parse_coin() {
@@ -148,9 +149,9 @@ accounts_registry_upsert() {
 		}]
 		| sort_by(.name)
 		' "${ACCOUNTS_FILE}" >"${tmp_file}"
-	chmod 644 "${tmp_file}"
+	chmod "${ACCOUNTS_FILE_MODE}" "${tmp_file}"
 	mv "${tmp_file}" "${ACCOUNTS_FILE}"
-	chmod 644 "${ACCOUNTS_FILE}"
+	chmod "${ACCOUNTS_FILE_MODE}" "${ACCOUNTS_FILE}"
 }
 
 accounts_registry_get_field() {
diff --git a/devnet/tests/common/account_registry_permissions_test.go b/devnet/tests/common/account_registry_permissions_test.go
new file mode 100644
index 00000000..d246a559
--- /dev/null
+++ b/devnet/tests/common/account_registry_permissions_test.go
@@ -0,0 +1,35 @@
+package common
+
+import (
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+func TestAccountRegistryContainingMnemonicsIsOwnerOnly(t *testing.T) {
+	scriptPath, err := filepath.Abs("../../scripts/account-registry.sh")
+	if err != nil {
+		t.Fatalf("resolve account registry script path: %v", err)
+	}
+
+	const scenario = `
+set -euo pipefail
+source "$1"
+accounts_registry_init "$2"
+
+ensure_accounts_registry
+[[ "$(stat -c '%a' "$ACCOUNTS_FILE")" == "600" ]]
+
+chmod 644 "$ACCOUNTS_FILE"
+ensure_accounts_registry
+[[ "$(stat -c '%a' "$ACCOUNTS_FILE")" == "600" ]]
+
+accounts_registry_upsert test-account lumera1fixture 'fixture mnemonic' cosmos 1ulume genesis ABC123
+[[ "$(stat -c '%a' "$ACCOUNTS_FILE")" == "600" ]]
+jq -e '. == [{name:"test-account",address:"lumera1fixture",mnemonic:"fixture mnemonic",type:"cosmos",funded:{display_amount:"0.000001",display_denom:"lume",base_amount:"1",base_denom:"ulume"},funding_key:"genesis",funding_txhash:"ABC123",created_at:(.[] | .created_at)}]' "$ACCOUNTS_FILE" >/dev/null
+`
+	cmd := exec.Command("bash", "-c", scenario, "account-registry-permissions-test", scriptPath, t.TempDir())
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("account registry must remain owner-only across every write path: %v\n%s", err, out)
+	}
+}

From 679243f72be93a8a8746976b679fc9b73b7da69a Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 15:29:37 +0000
Subject: [PATCH 08/11] fix(ops): bind migration prerequisites fail closed

---
 .../compatibility-manifest.schema.json        | 31 ++++++++++++-
 .../compatibility-manifest.template.json      |  1 +
 .../user-guides/operator-migration-runbook.md | 18 ++++++++
 .../user-guides/relayer-migration.md          | 31 ++++++++++---
 scripts/evmigration-common.sh                 | 28 +++++++++++
 tests/scripts/common.bats                     | 24 ++++++++++
 .../compatibility_manifest_schema_test.py     | 46 +++++++++++++++++++
 tests/scripts/devnet-makefile.bats            |  2 +
 8 files changed, 174 insertions(+), 7 deletions(-)

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
index c29e80a7..0e5c2a89 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -227,6 +227,11 @@
       "minLength": 3,
       "pattern": "^(?!.*(?:[Pp][Ll][Aa][Cc][Ee][Hh][Oo][Ll][Dd][Ee][Rr]|[Tt][Oo][Dd][Oo]|[Tt][Bb][Dd]|[Uu][Nn][Kk][Nn][Oo][Ww][Nn]|[Rr][Ee][Pp][Ll][Aa][Cc][Ee])(?:[^A-Za-z]|$))(?!.*<[^>]+>).+\\S$"
     },
+    "non_placeholder_argv": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!.*(?:[Pp][Ll][Aa][Cc][Ee][Hh][Oo][Ll][Dd][Ee][Rr]|[Tt][Oo][Dd][Oo]|[Tt][Bb][Dd]|[Uu][Nn][Kk][Nn][Oo][Ww][Nn]|[Rr][Ee][Pp][Ll][Aa][Cc][Ee])(?:[^A-Za-z]|$))(?!.*<[^>]+>)\\S(?:.*\\S)?$"
+    },
     "sha256": {
       "type": "string",
       "pattern": "^(?!0{64}$)[0-9a-f]{64}$"
@@ -300,9 +305,16 @@
     "pr2_implementation": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "tag", "commit", "sha256", "source", "no_echo_contract"],
+      "required": ["name", "release_path", "argv", "tag", "commit", "sha256", "source", "no_echo_contract"],
       "properties": {
         "name": { "type": "string", "minLength": 1 },
+        "release_path": { "$ref": "#/$defs/absolute_path" },
+        "argv": {
+          "type": "array",
+          "minItems": 1,
+          "prefixItems": [{ "$ref": "#/$defs/absolute_path" }],
+          "items": { "type": "string", "minLength": 1 }
+        },
         "tag": { "type": "string", "minLength": 1 },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
         "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
@@ -316,6 +328,23 @@
         {
           "properties": {
             "name": { "$ref": "#/$defs/non_placeholder" },
+            "release_path": {
+              "allOf": [
+                { "$ref": "#/$defs/absolute_path" },
+                { "$ref": "#/$defs/non_placeholder" }
+              ]
+            },
+            "argv": {
+              "type": "array",
+              "minItems": 1,
+              "prefixItems": [{
+                "allOf": [
+                  { "$ref": "#/$defs/absolute_path" },
+                  { "$ref": "#/$defs/non_placeholder" }
+                ]
+              }],
+              "items": { "$ref": "#/$defs/non_placeholder_argv" }
+            },
             "tag": { "$ref": "#/$defs/non_placeholder" },
             "commit": { "$ref": "#/$defs/commit" },
             "sha256": { "$ref": "#/$defs/sha256" },
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
index 484fabb0..df663aa3 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -172,6 +172,7 @@
   },
   "_verification": [
     "Release owner: replace every REPLACE_WITH value and every all-zero commit/hash; approval.status=approved is schema-invalid while any remain.",
+    "For destination_prestage_no_echo, bind implementation.release_path and the full implementation.argv. Require argv[0] to equal release_path, verify implementation.sha256 immediately before execution, and execute the argv array without eval or secret material in argv.",
     "Extract each release asset into a new mode-0700 directory. Verify the chain, SuperNode, sncli, and Hermes executable release path, tag, commit, version, source, and SHA-256; verify the container image artifact, registry source, and immutable digest; then verify every artifacts.bound_files release_path individually with sha256sum.",
     "Require operator_contracts.destination_prestage_no_echo.status=verified and bind its implementation name, tag, commit, SHA-256, source, and exact no-echo contract. Do not approve an unfinished or narrative-only PR-2 dependency.",
     "Run every validation command and attach sanitized evidence. Every validation status, including owned_testnet and portal_live, must be pass before approval is schema-valid.",
diff --git a/docs/evm-integration/user-guides/operator-migration-runbook.md b/docs/evm-integration/user-guides/operator-migration-runbook.md
index 13545f7e..05d7f70e 100644
--- a/docs/evm-integration/user-guides/operator-migration-runbook.md
+++ b/docs/evm-integration/user-guides/operator-migration-runbook.md
@@ -99,6 +99,24 @@ For a supernode or Hermes relayer, use the discovered config path in place of th
 
 **Required PR-2 compatibility dependency:** use only the release's approved destination pre-stage operation that implements the PR-2 no-echo contract. That operation must read the mnemonic from a hidden TTY or protected input file descriptor, never from argv, never echo it, never enable shell tracing, and print only non-secret key metadata. This PR-3 runbook does not claim that an unfinished PR-2 command exists in the current binary; if the release compatibility manifest does not name and hash an implementation of this contract, stop.
 
+The approved manifest must bind both the executable and its full argv. Verify the executable hash, require `argv[0]` to equal the approved absolute path, and execute the array without `eval` or operator substitutions:
+
+```bash
+PRESTAGE_IMPL=$(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.release_path' "$MANIFEST")
+PRESTAGE_SHA256=$(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.sha256' "$MANIFEST")
+mapfile -t PRESTAGE_ARGV < <(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.argv[]' "$MANIFEST")
+test "${PRESTAGE_IMPL#/}" != "$PRESTAGE_IMPL"
+test "${#PRESTAGE_ARGV[@]}" -gt 0
+test "${PRESTAGE_ARGV[0]}" = "$PRESTAGE_IMPL"
+printf '%s  %s\n' "$PRESTAGE_SHA256" "$PRESTAGE_IMPL" | sha256sum -c -
+
+# The implementation itself must obtain the mnemonic through its manifest-approved
+# hidden-TTY or protected-FD contract. Never append mnemonic material to this argv.
+sudo -u <service-user> -- "${PRESTAGE_ARGV[@]}"
+```
+
+Record the exact argv and sanitized public result in approval evidence. If the release's protected-FD form requires input redirection, use only the separately approved custody procedure; redirection must not alter argv or expose the mnemonic.
+
 After PR-2 pre-staging, verify the destination locally using the same binary/home/backend/location:
 
 ```bash
diff --git a/docs/evm-integration/user-guides/relayer-migration.md b/docs/evm-integration/user-guides/relayer-migration.md
index 7729bf9e..0853c4df 100644
--- a/docs/evm-integration/user-guides/relayer-migration.md
+++ b/docs/evm-integration/user-guides/relayer-migration.md
@@ -16,14 +16,18 @@
 > LUMERAD_SHA256=$(jq -er '.artifacts.chain_executable.sha256' "$MANIFEST")
 > MIGRATE_ACCOUNT=$(jq -er '.artifacts.bound_files["scripts/migrate-account.sh"].release_path' "$MANIFEST")
 > MIGRATE_ACCOUNT_SHA256=$(jq -er '.artifacts.bound_files["scripts/migrate-account.sh"].sha256' "$MANIFEST")
+> EVMIGRATION_COMMON=$(jq -er '.artifacts.bound_files["scripts/evmigration-common.sh"].release_path' "$MANIFEST")
+> EVMIGRATION_COMMON_SHA256=$(jq -er '.artifacts.bound_files["scripts/evmigration-common.sh"].sha256' "$MANIFEST")
 > HERMES_HOME=/absolute/discovered/hermes/home
 > HERMES_CONFIG="$HERMES_HOME/config.toml"
 > test "${HERMES#/}" != "$HERMES" && test "${LUMERAD#/}" != "$LUMERAD"
-> test "${MIGRATE_ACCOUNT#/}" != "$MIGRATE_ACCOUNT" && test "${HERMES_HOME#/}" != "$HERMES_HOME"
-> printf '%s  %s\n%s  %s\n%s  %s\n' \
+> test "${MIGRATE_ACCOUNT#/}" != "$MIGRATE_ACCOUNT" && test "${EVMIGRATION_COMMON#/}" != "$EVMIGRATION_COMMON"
+> test "${HERMES_HOME#/}" != "$HERMES_HOME"
+> printf '%s  %s\n%s  %s\n%s  %s\n%s  %s\n' \
 >   "$HERMES_SHA256" "$HERMES" \
 >   "$LUMERAD_SHA256" "$LUMERAD" \
->   "$MIGRATE_ACCOUNT_SHA256" "$MIGRATE_ACCOUNT" | sha256sum -c -
+>   "$MIGRATE_ACCOUNT_SHA256" "$MIGRATE_ACCOUNT" \
+>   "$EVMIGRATION_COMMON_SHA256" "$EVMIGRATION_COMMON" | sha256sum -c -
 > test -f "$HERMES_CONFIG"
 > ```
 
@@ -119,8 +123,15 @@ sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 | grep relayer-evm-gate
-# the printed address MUST equal $NEWADDR. If it does not, STOP — do not migrate.
+if ! HERMES_GATE_ADDR=$(
+  sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 |
+    EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
+      'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer-evm-gate "$EXPECTED_ADDR"'
+); then
+  echo 'Hermes destination-address gate failed; do not migrate' >&2
+  exit 1
+fi
+test "$HERMES_GATE_ADDR" = "$NEWADDR"
 sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys delete --chain lumera-mainnet-1 --key-name relayer-evm-gate
 ```
 
@@ -166,7 +177,15 @@ sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 | grep ' relayer '   # MUST show $NEWADDR
+if ! HERMES_ACTIVE_ADDR=$(
+  sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 |
+    EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
+      'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer "$EXPECTED_ADDR"'
+); then
+  echo 'Active Hermes key does not control the migrated destination; keep relayer stopped' >&2
+  exit 1
+fi
+test "$HERMES_ACTIVE_ADDR" = "$NEWADDR"
 ```
 
 ### Step 6 — Restart and verify
diff --git a/scripts/evmigration-common.sh b/scripts/evmigration-common.sh
index ce00ae4c..f89748de 100755
--- a/scripts/evmigration-common.sh
+++ b/scripts/evmigration-common.sh
@@ -114,6 +114,34 @@ _role_color() { printf '%s%s%s' "$1" "$2" "$_C_RESET"; }
 legacy_value() { _role_color "$_C_LEGACY" "$1"; }
 new_value() { _role_color "$_C_NEW" "$1"; }
 
+# Parse `hermes keys list` output and fail closed unless exactly one named key
+# derives the expected address. Hermes v1.13 has no JSON output for this command.
+# Usage: hermes keys list ... | require_hermes_key_address <key-name> <expected-address>
+require_hermes_key_address() {
+  if (( $# != 2 )) || [[ -z "$1" || -z "$2" ]]; then
+    log_error "require_hermes_key_address requires key name and expected address"
+    return 1
+  fi
+
+  local key_name="$1" expected_address="$2" matches
+  matches=$(awk -v key="$key_name" '
+    $1 == "-" && $2 == key && NF == 3 && $3 ~ /^\([^()]+\)$/ {
+      print substr($3, 2, length($3) - 2)
+    }
+  ')
+
+  if [[ -z "$matches" || "$matches" == *$'\n'* ]]; then
+    log_error "expected exactly one Hermes key named $key_name"
+    return 1
+  fi
+  if [[ "$matches" != "$expected_address" ]]; then
+    log_error "Hermes key $key_name derives $matches, which does not match expected destination $expected_address"
+    return 1
+  fi
+
+  printf '%s\n' "$matches"
+}
+
 # ---- Flag parsing -----------------------------------------------------------
 
 # _require_value <flag-name> <arg-count> <next-arg-or-empty>
diff --git a/tests/scripts/common.bats b/tests/scripts/common.bats
index 40c1f535..23e297dd 100644
--- a/tests/scripts/common.bats
+++ b/tests/scripts/common.bats
@@ -1134,3 +1134,27 @@ JSON
   [[ "$output" == *"Keyring location: $kr (explicit --keyring-dir)"* ]]
   [[ "$output" != *"test (default)"* ]]
 }
+
+@test "require_hermes_key_address accepts one exact address match" {
+  run bash -c 'source '"$SCRIPTS_DIR"'/evmigration-common.sh; printf "%s\n" "SUCCESS" "- relayer-evm-gate (lumera1expected)" | require_hermes_key_address relayer-evm-gate lumera1expected'
+  [ "$status" -eq 0 ]
+  [ "$output" = "lumera1expected" ]
+}
+
+@test "require_hermes_key_address rejects an address mismatch" {
+  run bash -c 'source '"$SCRIPTS_DIR"'/evmigration-common.sh; printf "%s\n" "- relayer-evm-gate (lumera1wrong)" | require_hermes_key_address relayer-evm-gate lumera1expected'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"does not match expected destination"* ]]
+}
+
+@test "require_hermes_key_address rejects a missing key" {
+  run bash -c 'source '"$SCRIPTS_DIR"'/evmigration-common.sh; printf "%s\n" "- other-key (lumera1expected)" | require_hermes_key_address relayer-evm-gate lumera1expected'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"exactly one Hermes key"* ]]
+}
+
+@test "require_hermes_key_address rejects duplicate key rows" {
+  run bash -c 'source '"$SCRIPTS_DIR"'/evmigration-common.sh; printf "%s\n" "- relayer-evm-gate (lumera1expected)" "- relayer-evm-gate (lumera1expected)" | require_hermes_key_address relayer-evm-gate lumera1expected'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"exactly one Hermes key"* ]]
+}
diff --git a/tests/scripts/compatibility_manifest_schema_test.py b/tests/scripts/compatibility_manifest_schema_test.py
index b7a90644..d534ba34 100644
--- a/tests/scripts/compatibility_manifest_schema_test.py
+++ b/tests/scripts/compatibility_manifest_schema_test.py
@@ -64,6 +64,14 @@ def approved_manifest(template):
         "status": "verified",
         "implementation": {
             "name": "destination-prestage",
+            "release_path": "/opt/lumera/bin/destination-prestage",
+            "argv": [
+                "/opt/lumera/bin/destination-prestage",
+                "--home",
+                "/var/lib/lumera",
+                "--protected-fd",
+                "3",
+            ],
             "tag": "v1.20.0",
             "commit": "6" * 40,
             "sha256": "7" * 64,
@@ -132,6 +140,44 @@ def test_approved_relative_bound_file_release_path_is_rejected(self):
         ] = "scripts/migrate-validator.sh"
         self.assert_invalid(unsafe)
 
+    def test_approved_prestage_requires_absolute_runtime_binding(self):
+        missing_path = copy.deepcopy(self.approved)
+        del missing_path["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["release_path"]
+        self.assert_invalid(missing_path)
+
+        relative_path = copy.deepcopy(self.approved)
+        relative_path["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["release_path"] = "bin/destination-prestage"
+        self.assert_invalid(relative_path)
+
+        placeholder_path = copy.deepcopy(self.approved)
+        placeholder_path["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["release_path"] = "/REPLACE_WITH_DESTINATION_PRESTAGE"
+        self.assert_invalid(placeholder_path)
+
+    def test_approved_prestage_requires_exact_non_placeholder_argv(self):
+        missing_argv = copy.deepcopy(self.approved)
+        del missing_argv["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["argv"]
+        self.assert_invalid(missing_argv)
+
+        relative_executable = copy.deepcopy(self.approved)
+        relative_executable["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["argv"][0] = "bin/destination-prestage"
+        self.assert_invalid(relative_executable)
+
+        placeholder_argument = copy.deepcopy(self.approved)
+        placeholder_argument["operator_contracts"]["destination_prestage_no_echo"][
+            "implementation"
+        ]["argv"][2] = "REPLACE_WITH_HOME"
+        self.assert_invalid(placeholder_argument)
+
     def test_url_sources_are_not_constrained_as_runtime_paths(self):
         manifest = copy.deepcopy(self.approved)
         manifest["release"]["release_url"] = "https://example.com/release"
diff --git a/tests/scripts/devnet-makefile.bats b/tests/scripts/devnet-makefile.bats
index f4a81abe..fde74ceb 100644
--- a/tests/scripts/devnet-makefile.bats
+++ b/tests/scripts/devnet-makefile.bats
@@ -18,6 +18,7 @@ teardown() {
 
 @test "external version staging uses downloaded binaries without requiring claims" {
   run make -C "$REPO_ROOT" -n devnet-stage-external-version \
+    MAKE=/bin/true \
     VERSION=v1.12.0 \
     EXTERNAL_GENESIS_FILE="$EXTERNAL_GENESIS"
 
@@ -36,6 +37,7 @@ teardown() {
 
 @test "remote version target syncs staged runtime and runs docker remotely" {
   run make -C "$REPO_ROOT" -n devnet-new-remote-version \
+    MAKE=/bin/true \
     VERSION=v1.12.0 \
     EXTERNAL_GENESIS_FILE="$EXTERNAL_GENESIS" \
     REMOTE_DEVNET_HOST=example-devnet \

From 59d4e81efd3d122ea7cb23f8f12a8c859ebe7917 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 15:51:55 +0000
Subject: [PATCH 09/11] fix(ops): remove manifest and relayer gate ambiguity

---
 .../compatibility-manifest.schema.json        |  9 +------
 .../compatibility-manifest.template.json      |  2 +-
 .../user-guides/operator-migration-runbook.md |  5 ++--
 .../user-guides/relayer-migration.md          | 24 +++++++++++--------
 scripts/evmigration-common.sh                 |  4 ++--
 .../compatibility_manifest_schema_test.py     | 19 +++------------
 6 files changed, 23 insertions(+), 40 deletions(-)

diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
index 0e5c2a89..68547b64 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.schema.json
@@ -305,10 +305,9 @@
     "pr2_implementation": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "release_path", "argv", "tag", "commit", "sha256", "source", "no_echo_contract"],
+      "required": ["name", "argv", "tag", "commit", "sha256", "source", "no_echo_contract"],
       "properties": {
         "name": { "type": "string", "minLength": 1 },
-        "release_path": { "$ref": "#/$defs/absolute_path" },
         "argv": {
           "type": "array",
           "minItems": 1,
@@ -328,12 +327,6 @@
         {
           "properties": {
             "name": { "$ref": "#/$defs/non_placeholder" },
-            "release_path": {
-              "allOf": [
-                { "$ref": "#/$defs/absolute_path" },
-                { "$ref": "#/$defs/non_placeholder" }
-              ]
-            },
             "argv": {
               "type": "array",
               "minItems": 1,
diff --git a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
index df663aa3..fe41cb8f 100644
--- a/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
+++ b/docs/evm-integration/operator-artifacts/compatibility-manifest.template.json
@@ -172,7 +172,7 @@
   },
   "_verification": [
     "Release owner: replace every REPLACE_WITH value and every all-zero commit/hash; approval.status=approved is schema-invalid while any remain.",
-    "For destination_prestage_no_echo, bind implementation.release_path and the full implementation.argv. Require argv[0] to equal release_path, verify implementation.sha256 immediately before execution, and execute the argv array without eval or secret material in argv.",
+    "For destination_prestage_no_echo, bind the full implementation.argv with its sole executable path in argv[0]. Require argv[0] to be absolute, verify implementation.sha256 against argv[0] immediately before execution, and execute the argv array without eval or secret material in argv.",
     "Extract each release asset into a new mode-0700 directory. Verify the chain, SuperNode, sncli, and Hermes executable release path, tag, commit, version, source, and SHA-256; verify the container image artifact, registry source, and immutable digest; then verify every artifacts.bound_files release_path individually with sha256sum.",
     "Require operator_contracts.destination_prestage_no_echo.status=verified and bind its implementation name, tag, commit, SHA-256, source, and exact no-echo contract. Do not approve an unfinished or narrative-only PR-2 dependency.",
     "Run every validation command and attach sanitized evidence. Every validation status, including owned_testnet and portal_live, must be pass before approval is schema-valid.",
diff --git a/docs/evm-integration/user-guides/operator-migration-runbook.md b/docs/evm-integration/user-guides/operator-migration-runbook.md
index 05d7f70e..75ac3133 100644
--- a/docs/evm-integration/user-guides/operator-migration-runbook.md
+++ b/docs/evm-integration/user-guides/operator-migration-runbook.md
@@ -99,15 +99,14 @@ For a supernode or Hermes relayer, use the discovered config path in place of th
 
 **Required PR-2 compatibility dependency:** use only the release's approved destination pre-stage operation that implements the PR-2 no-echo contract. That operation must read the mnemonic from a hidden TTY or protected input file descriptor, never from argv, never echo it, never enable shell tracing, and print only non-secret key metadata. This PR-3 runbook does not claim that an unfinished PR-2 command exists in the current binary; if the release compatibility manifest does not name and hash an implementation of this contract, stop.
 
-The approved manifest must bind both the executable and its full argv. Verify the executable hash, require `argv[0]` to equal the approved absolute path, and execute the array without `eval` or operator substitutions:
+The approved manifest binds the executable exactly once, as `argv[0]` of its full argv. Verify that absolute path's hash and execute the array without `eval` or operator substitutions:
 
 ```bash
-PRESTAGE_IMPL=$(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.release_path' "$MANIFEST")
 PRESTAGE_SHA256=$(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.sha256' "$MANIFEST")
 mapfile -t PRESTAGE_ARGV < <(jq -er '.operator_contracts.destination_prestage_no_echo.implementation.argv[]' "$MANIFEST")
+PRESTAGE_IMPL=${PRESTAGE_ARGV[0]:-}
 test "${PRESTAGE_IMPL#/}" != "$PRESTAGE_IMPL"
 test "${#PRESTAGE_ARGV[@]}" -gt 0
-test "${PRESTAGE_ARGV[0]}" = "$PRESTAGE_IMPL"
 printf '%s  %s\n' "$PRESTAGE_SHA256" "$PRESTAGE_IMPL" | sha256sum -c -
 
 # The implementation itself must obtain the mnemonic through its manifest-approved
diff --git a/docs/evm-integration/user-guides/relayer-migration.md b/docs/evm-integration/user-guides/relayer-migration.md
index 0853c4df..29ae9e8c 100644
--- a/docs/evm-integration/user-guides/relayer-migration.md
+++ b/docs/evm-integration/user-guides/relayer-migration.md
@@ -123,11 +123,13 @@ sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-if ! HERMES_GATE_ADDR=$(
-  sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 |
-    EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
-      'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer-evm-gate "$EXPECTED_ADDR"'
-); then
+if ! HERMES_KEYS_OUTPUT=$(sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1); then
+  echo 'Hermes keys list failed; do not migrate' >&2
+  exit 1
+fi
+if ! HERMES_GATE_ADDR=$(printf '%s\n' "$HERMES_KEYS_OUTPUT" |
+  EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
+    'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer-evm-gate "$EXPECTED_ADDR"'); then
   echo 'Hermes destination-address gate failed; do not migrate' >&2
   exit 1
 fi
@@ -177,11 +179,13 @@ sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys add \
   --mnemonic-file /run/secrets/relayer-evm.mnemonic \
   --hd-path "m/44'/60'/0'/0/0"
 
-if ! HERMES_ACTIVE_ADDR=$(
-  sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1 |
-    EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
-      'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer "$EXPECTED_ADDR"'
-); then
+if ! HERMES_KEYS_OUTPUT=$(sudo -u <relayer-service-user> "$HERMES" --config "$HERMES_CONFIG" keys list --chain lumera-mainnet-1); then
+  echo 'Hermes keys list failed; keep relayer stopped' >&2
+  exit 1
+fi
+if ! HERMES_ACTIVE_ADDR=$(printf '%s\n' "$HERMES_KEYS_OUTPUT" |
+  EVMIGRATION_COMMON="$EVMIGRATION_COMMON" EXPECTED_ADDR="$NEWADDR" bash -c \
+    'source "$EVMIGRATION_COMMON"; require_hermes_key_address relayer "$EXPECTED_ADDR"'); then
   echo 'Active Hermes key does not control the migrated destination; keep relayer stopped' >&2
   exit 1
 fi
diff --git a/scripts/evmigration-common.sh b/scripts/evmigration-common.sh
index f89748de..56ec993f 100755
--- a/scripts/evmigration-common.sh
+++ b/scripts/evmigration-common.sh
@@ -114,8 +114,8 @@ _role_color() { printf '%s%s%s' "$1" "$2" "$_C_RESET"; }
 legacy_value() { _role_color "$_C_LEGACY" "$1"; }
 new_value() { _role_color "$_C_NEW" "$1"; }
 
-# Parse `hermes keys list` output and fail closed unless exactly one named key
-# derives the expected address. Hermes v1.13 has no JSON output for this command.
+# Parse the pinned `hermes keys list` text rows and fail closed unless exactly
+# one named key derives the expected address.
 # Usage: hermes keys list ... | require_hermes_key_address <key-name> <expected-address>
 require_hermes_key_address() {
   if (( $# != 2 )) || [[ -z "$1" || -z "$2" ]]; then
diff --git a/tests/scripts/compatibility_manifest_schema_test.py b/tests/scripts/compatibility_manifest_schema_test.py
index d534ba34..e1299221 100644
--- a/tests/scripts/compatibility_manifest_schema_test.py
+++ b/tests/scripts/compatibility_manifest_schema_test.py
@@ -64,7 +64,6 @@ def approved_manifest(template):
         "status": "verified",
         "implementation": {
             "name": "destination-prestage",
-            "release_path": "/opt/lumera/bin/destination-prestage",
             "argv": [
                 "/opt/lumera/bin/destination-prestage",
                 "--home",
@@ -140,23 +139,17 @@ def test_approved_relative_bound_file_release_path_is_rejected(self):
         ] = "scripts/migrate-validator.sh"
         self.assert_invalid(unsafe)
 
-    def test_approved_prestage_requires_absolute_runtime_binding(self):
-        missing_path = copy.deepcopy(self.approved)
-        del missing_path["operator_contracts"]["destination_prestage_no_echo"][
-            "implementation"
-        ]["release_path"]
-        self.assert_invalid(missing_path)
-
+    def test_approved_prestage_argv_zero_is_the_absolute_runtime_binding(self):
         relative_path = copy.deepcopy(self.approved)
         relative_path["operator_contracts"]["destination_prestage_no_echo"][
             "implementation"
-        ]["release_path"] = "bin/destination-prestage"
+        ]["argv"][0] = "bin/destination-prestage"
         self.assert_invalid(relative_path)
 
         placeholder_path = copy.deepcopy(self.approved)
         placeholder_path["operator_contracts"]["destination_prestage_no_echo"][
             "implementation"
-        ]["release_path"] = "/REPLACE_WITH_DESTINATION_PRESTAGE"
+        ]["argv"][0] = "/REPLACE_WITH_DESTINATION_PRESTAGE"
         self.assert_invalid(placeholder_path)
 
     def test_approved_prestage_requires_exact_non_placeholder_argv(self):
@@ -166,12 +159,6 @@ def test_approved_prestage_requires_exact_non_placeholder_argv(self):
         ]["argv"]
         self.assert_invalid(missing_argv)
 
-        relative_executable = copy.deepcopy(self.approved)
-        relative_executable["operator_contracts"]["destination_prestage_no_echo"][
-            "implementation"
-        ]["argv"][0] = "bin/destination-prestage"
-        self.assert_invalid(relative_executable)
-
         placeholder_argument = copy.deepcopy(self.approved)
         placeholder_argument["operator_contracts"]["destination_prestage_no_echo"][
             "implementation"

From fd15ff34b126f7f911b9d8e72cdd4dd7131c34e2 Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Tue, 28 Jul 2026 09:52:38 +0000
Subject: [PATCH 10/11] app: register v1.20.2 migration-only upgrade handler

Register the coordinated v1.20.2 upgrade boundary for the evmigration fixes. The handler runs module migrations only and declares no store changes or historical state repair.
---
 app/upgrades/upgrades.go             |  7 +++++++
 app/upgrades/upgrades_test.go        | 12 ++++++++++++
 app/upgrades/v1_20_2/upgrade.go      |  4 ++++
 app/upgrades/v1_20_2/upgrade_test.go | 11 +++++++++++
 4 files changed, 34 insertions(+)
 create mode 100644 app/upgrades/v1_20_2/upgrade.go
 create mode 100644 app/upgrades/v1_20_2/upgrade_test.go

diff --git a/app/upgrades/upgrades.go b/app/upgrades/upgrades.go
index 6345c5dc..b3957750 100644
--- a/app/upgrades/upgrades.go
+++ b/app/upgrades/upgrades.go
@@ -18,6 +18,7 @@ import (
 	upgrade_v1_12_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_12_0"
 	upgrade_v1_20_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_0"
 	upgrade_v1_20_1 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_1"
+	upgrade_v1_20_2 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_2"
 	upgrade_v1_6_1 "github.com/LumeraProtocol/lumera/app/upgrades/v1_6_1"
 	upgrade_v1_8_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_8_0"
 	upgrade_v1_8_4 "github.com/LumeraProtocol/lumera/app/upgrades/v1_8_4"
@@ -43,6 +44,7 @@ import (
 // | v1.12.0 | custom   | none (Everlight in supernode)     | Runs migrations; Everlight logic embedded in x/supernode
 // | v1.20.0 | custom   | non-mainnet: add feemarket, precisebank, vm, erc20 | EVM bring-up; gated to non-mainnet (mainnet runs it via v1.20.1)
 // | v1.20.1 | custom   | state-driven add-only: feemarket, precisebank, vm, erc20 | EVM bring-up when EVM absent (any network, incl. direct 1.12.0->1.20.1); migrations-only hotfix when EVM already present. Add-only store loader mounts only missing keys.
+// | v1.20.2 | standard | none                              | Migrations only; no historical state repair
 // =================================================================================================================================
 
 type UpgradeConfig struct {
@@ -75,6 +77,7 @@ var upgradeNames = []string{
 	upgrade_v1_12_0.UpgradeName,
 	upgrade_v1_20_0.UpgradeName,
 	upgrade_v1_20_1.UpgradeName,
+	upgrade_v1_20_2.UpgradeName,
 }
 
 var NoUpgradeConfig = UpgradeConfig{
@@ -177,6 +180,10 @@ func SetupUpgrades(upgradeName string, params appParams.AppUpgradeParams) (Upgra
 			StoreUpgrade: &upgrade_v1_20_0.StoreUpgrades,
 			Handler:      upgrade_v1_20_1.CreateUpgradeHandler(params),
 		}, true
+	case upgrade_v1_20_2.UpgradeName:
+		return UpgradeConfig{
+			Handler: standardUpgradeHandler(upgrade_v1_20_2.UpgradeName, params),
+		}, true
 
 	// add future upgrades here
 	default:
diff --git a/app/upgrades/upgrades_test.go b/app/upgrades/upgrades_test.go
index 58995fd7..33651c3a 100644
--- a/app/upgrades/upgrades_test.go
+++ b/app/upgrades/upgrades_test.go
@@ -18,6 +18,7 @@ import (
 	upgrade_v1_12_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_12_0"
 	upgrade_v1_20_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_0"
 	upgrade_v1_20_1 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_1"
+	upgrade_v1_20_2 "github.com/LumeraProtocol/lumera/app/upgrades/v1_20_2"
 	upgrade_v1_6_1 "github.com/LumeraProtocol/lumera/app/upgrades/v1_6_1"
 	upgrade_v1_8_0 "github.com/LumeraProtocol/lumera/app/upgrades/v1_8_0"
 	upgrade_v1_8_4 "github.com/LumeraProtocol/lumera/app/upgrades/v1_8_4"
@@ -47,6 +48,7 @@ func TestUpgradeNamesOrder(t *testing.T) {
 		upgrade_v1_12_0.UpgradeName,
 		upgrade_v1_20_0.UpgradeName,
 		upgrade_v1_20_1.UpgradeName,
+		upgrade_v1_20_2.UpgradeName,
 	}
 	require.Equal(t, expected, upgradeNames, "upgradeNames should stay in ascending order")
 }
@@ -225,6 +227,16 @@ func TestV1201CarriesEVMBringupOnAllNetworks(t *testing.T) {
 	}
 }
 
+func TestV1202IsMigrationOnlyOnAllNetworks(t *testing.T) {
+	for _, chainID := range []string{"lumera-mainnet-1", "lumera-testnet-2", "lumera-devnet-1"} {
+		params := newTestUpgradeParams(chainID)
+		config, found := SetupUpgrades(upgrade_v1_20_2.UpgradeName, params)
+		require.True(t, found)
+		require.NotNil(t, config.Handler, "v1.20.2 must register a handler on %s", chainID)
+		require.Nil(t, config.StoreUpgrade, "v1.20.2 must not alter stores on %s", chainID)
+	}
+}
+
 func newTestUpgradeParams(chainID string) appParams.AppUpgradeParams {
 	return appParams.AppUpgradeParams{
 		ChainID:       chainID,
diff --git a/app/upgrades/v1_20_2/upgrade.go b/app/upgrades/v1_20_2/upgrade.go
new file mode 100644
index 00000000..061c7953
--- /dev/null
+++ b/app/upgrades/v1_20_2/upgrade.go
@@ -0,0 +1,4 @@
+package v1_20_2
+
+// UpgradeName is the on-chain name used for this upgrade.
+const UpgradeName = "v1.20.2"
diff --git a/app/upgrades/v1_20_2/upgrade_test.go b/app/upgrades/v1_20_2/upgrade_test.go
new file mode 100644
index 00000000..72ff542a
--- /dev/null
+++ b/app/upgrades/v1_20_2/upgrade_test.go
@@ -0,0 +1,11 @@
+package v1_20_2
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestUpgradeName(t *testing.T) {
+	require.Equal(t, "v1.20.2", UpgradeName)
+}

From 5d3f2b588e015e5d9b1a2566f9652f93e2fbeb8d Mon Sep 17 00:00:00 2001
From: Matee ullah Malik <mateeullahmalik@hotmail.com>
Date: Fri, 31 Jul 2026 00:53:35 +0000
Subject: [PATCH 11/11] test(upgrades): drop stale migration-only store
 assertion for v1.20.2

TestV1202IsMigrationOnlyOnAllNetworks asserted config.StoreUpgrade == nil.
That premise held for testnet (v1.20.0 already mounted the EVM stores) and was
wrong for mainnet, which is still on 1.12.0 and has none of them. The
mainnet-shaped devnet rehearsal disproved it: every validator crash-looped with

  panic: version of store evmigration mismatch root store's version;
  expected 155 got 0; new stores should be added using StoreUpgrades

v1.20.2 now declares the EVM store additions on every network, paired with the
add-only store loader that mounts only keys absent from committed state - a
no-op on a chain that already ran v1.20.0, a full bring-up on one that did not.

Renamed to TestV1202RegistersOnAllNetworks and reduced to the registration
assertion. Store expectations live in v1_20_2_store_test.go, which asserts the
five store keys and the add-only loader pairing.

This is the third copy of the same wrong premise found and removed; the surviving
assertions are the rehearsal-proven ones.
---
 app/upgrades/upgrades_test.go | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/app/upgrades/upgrades_test.go b/app/upgrades/upgrades_test.go
index c1a6d10d..fa6e2569 100644
--- a/app/upgrades/upgrades_test.go
+++ b/app/upgrades/upgrades_test.go
@@ -228,13 +228,26 @@ func TestV1201CarriesEVMBringupOnAllNetworks(t *testing.T) {
 	}
 }
 
-func TestV1202IsMigrationOnlyOnAllNetworks(t *testing.T) {
+// TestV1202RegistersOnAllNetworks asserts v1.20.2 is wired up everywhere.
+//
+// NOTE: this test previously also asserted `config.StoreUpgrade == nil`, on the
+// reasoning that v1.20.2 is a migration-only carrier. That premise was correct
+// for testnet and WRONG for mainnet, and the mainnet-shaped devnet rehearsal
+// disproved it: mainnet is still on 1.12.0 with NO EVM stores, so declaring no
+// StoreUpgrades made every validator crash-loop with
+//
+//	panic: version of store evmigration mismatch root store's version;
+//	expected 155 got 0; new stores should be added using StoreUpgrades
+//
+// v1.20.2 therefore declares the EVM store additions on every network, paired
+// with the add-only store loader that mounts only the keys missing from
+// committed state. Store expectations now live in v1_20_2_store_test.go.
+func TestV1202RegistersOnAllNetworks(t *testing.T) {
 	for _, chainID := range []string{"lumera-mainnet-1", "lumera-testnet-2", "lumera-devnet-1"} {
 		params := newTestUpgradeParams(chainID)
 		config, found := SetupUpgrades(upgrade_v1_20_2.UpgradeName, params)
 		require.True(t, found)
 		require.NotNil(t, config.Handler, "v1.20.2 must register a handler on %s", chainID)
-		require.Nil(t, config.StoreUpgrade, "v1.20.2 must not alter stores on %s", chainID)
 	}
 }