diff --git a/.github/scripts/release/r2/publish.sh b/.github/scripts/release/r2/publish.sh
index 0262ea2..1bb23e3 100755
--- a/.github/scripts/release/r2/publish.sh
+++ b/.github/scripts/release/r2/publish.sh
@@ -117,6 +117,10 @@ metadata = {
     },
 }
 
+guard_hash = env.get("GUARD_VERSION_HASH", "")
+if guard_hash:
+    metadata["guard"] = {"version": {"hash": guard_hash}}
+
 if env["RELEASE_CHANNEL"] == "beta":
     match = re.match(r"^v?(\d+\.\d+\.\d+)-beta\.([1-9][0-9]*)$", env["RELEASE_VERSION"])
     if not match:
@@ -131,6 +135,9 @@ if env["RELEASE_CHANNEL"] == "beta":
     metadata["betaNumber"] = beta_number
     metadata["betaVersion"] = env["RELEASE_VERSION"]
     metadata["stateSource"] = env.get("STATE_SOURCE") or "workflow input"
+else:
+    metadata["stableVersion"] = env["RELEASE_VERSION"]
+    metadata["stateSource"] = env.get("STATE_SOURCE") or "workflow input"
 
 Path(env["METADATA_PATH"]).write_text(json.dumps(metadata, indent=2) + "\n", encoding="utf-8")
 PY
diff --git a/.github/workflows/guard.yml b/.github/workflows/guard.yml
index a55e9fc..9598160 100644
--- a/.github/workflows/guard.yml
+++ b/.github/workflows/guard.yml
@@ -30,15 +30,6 @@ jobs:
           components: rustfmt, clippy
 
       - name: Format
-        run: cargo fmt --all --check
-
-      - name: Clippy
-        run: cargo clippy --locked --workspace --all-targets -- -D warnings
-
-      - name: Test
-        run: cargo test --locked --workspace
-
-      - name: Install Flavor
         if: runner.os != 'Windows'
         run: |
           set -euo pipefail
@@ -55,5 +46,16 @@ jobs:
           & (Join-Path $env:RUNNER_TEMP 'manage-flavor.ps1') install --bin-dir $binDir
           $binDir | Out-File -Append -Encoding utf8 $env:GITHUB_PATH
 
-      - name: Flavor self-check
-        run: flavor check --root . --config flavor.toml
+      - name: Guard
+        shell: bash
+        run: |
+          set -euo pipefail
+          cargo build --quiet --locked -p runseal
+          exe=runseal
+          if [ "${RUNNER_OS:-}" = "Windows" ]; then
+            exe=runseal.exe
+          fi
+          bin_dir="$PWD/.local/tmp/ci-guard-bin"
+          mkdir -p "$bin_dir"
+          cp "target/debug/$exe" "$bin_dir/$exe"
+          PATH="$bin_dir:$PWD/target/debug:$PATH" "$bin_dir/$exe" :guard
diff --git a/.github/workflows/release-beta.yml b/.github/workflows/release-beta.yml
index ad4f385..a9d567f 100644
--- a/.github/workflows/release-beta.yml
+++ b/.github/workflows/release-beta.yml
@@ -51,6 +51,12 @@ jobs:
         id: beta
         run: python3 .github/scripts/release/metadata/beta.py
 
+      - name: Guard version policy
+        shell: bash
+        run: |
+          set -euo pipefail
+          PATH="$PWD/target/debug:$PATH" cargo run --quiet --locked -p runseal -- :guard version-check
+
   verify:
     needs: metadata
     runs-on: ubuntu-latest
@@ -73,6 +79,7 @@ jobs:
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
       - name: Install Flavor
+        shell: bash
         run: |
           set -euo pipefail
           curl -fsSL https://flavor.perish.uk/manage.sh -o "$RUNNER_TEMP/manage-flavor.sh"
@@ -157,6 +164,15 @@ jobs:
           path: dist/${{ needs.metadata.outputs.release_version }}
           merge-multiple: true
 
+      - name: Resolve guard version hash
+        id: guard_hash
+        shell: bash
+        run: |
+          set -euo pipefail
+          PATH="$PWD/target/debug:$PATH"
+          hash=$(cargo run --quiet --locked -p runseal -- :guard version-hash)
+          echo "value=$hash" >> "$GITHUB_OUTPUT"
+
       - name: Create checksums
         run: sh .github/scripts/release/assets/checksums.sh "${RELEASE_VERSION}" "${RELEASE_ROOT}"
 
@@ -168,6 +184,8 @@ jobs:
 
       - name: Publish to R2
         id: r2
+        env:
+          GUARD_VERSION_HASH: ${{ steps.guard_hash.outputs.value }}
         run: bash .github/scripts/release/r2/publish.sh
 
       - name: Verify R2 publish
diff --git a/.github/workflows/release-stable.yml b/.github/workflows/release-stable.yml
index 442daf4..4b83397 100644
--- a/.github/workflows/release-stable.yml
+++ b/.github/workflows/release-stable.yml
@@ -50,6 +50,12 @@ jobs:
         id: stable
         run: python3 .github/scripts/release/metadata/stable.py
 
+      - name: Guard version policy
+        shell: bash
+        run: |
+          set -euo pipefail
+          PATH="$PWD/target/debug:$PATH" cargo run --quiet --locked -p runseal -- :guard version-check
+
   verify:
     needs: metadata
     runs-on: ubuntu-latest
@@ -72,6 +78,7 @@ jobs:
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
       - name: Install Flavor
+        shell: bash
         run: |
           set -euo pipefail
           curl -fsSL https://flavor.perish.uk/manage.sh -o "$RUNNER_TEMP/manage-flavor.sh"
@@ -155,6 +162,15 @@ jobs:
           path: dist/${{ needs.metadata.outputs.release_version }}
           merge-multiple: true
 
+      - name: Resolve guard version hash
+        id: guard_hash
+        shell: bash
+        run: |
+          set -euo pipefail
+          PATH="$PWD/target/debug:$PATH"
+          hash=$(cargo run --quiet --locked -p runseal -- :guard version-hash)
+          echo "value=$hash" >> "$GITHUB_OUTPUT"
+
       - name: Create checksums
         run: sh .github/scripts/release/assets/checksums.sh "${RELEASE_VERSION}" "${RELEASE_ROOT}"
 
@@ -166,6 +182,8 @@ jobs:
 
       - name: Publish to R2
         id: r2
+        env:
+          GUARD_VERSION_HASH: ${{ steps.guard_hash.outputs.value }}
         run: bash .github/scripts/release/r2/publish.sh
 
       - name: Verify R2 publish
@@ -174,6 +192,7 @@ jobs:
         run: bash .github/scripts/release/r2/verify.sh
 
       - name: Create and push git tag
+        shell: bash
         run: |
           set -euo pipefail
           git config user.name "github-actions[bot]"
diff --git a/.runseal/hooks/commit-msg b/.runseal/hooks/commit-msg
new file mode 100644
index 0000000..10f9150
--- /dev/null
+++ b/.runseal/hooks/commit-msg
@@ -0,0 +1,39 @@
+#!/usr/bin/env sh
+# runseal init hook: generated by runseal :init
+set -eu
+
+if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then
+  echo "commit message file not found" >&2
+  exit 1
+fi
+
+subject=$(sed -n '
+/^[[:space:]]*#/d
+/[^[:space:]]/ {
+  s/^[[:space:]]*//
+  s/[[:space:]]*$//
+  p
+  q
+}
+' "$1")
+
+if [ -z "$subject" ]; then
+  echo "commit subject is empty" >&2
+  exit 1
+fi
+
+case "$subject" in
+  "Merge "*|"Revert "*|"fixup!"*|"squash!"*)
+    exit 0
+    ;;
+esac
+
+if ! printf '%s\n' "$subject" | grep -Eq '^[a-z][a-z0-9-]*(/[a-z0-9-]+)*: [^[:space:]].*'; then
+  echo "commit subject must look like '<area>: <imperative summary>'" >&2
+  echo "actual: $subject" >&2
+  exit 1
+fi
+
+if [ "${#subject}" -gt 72 ]; then
+  echo "warning: commit subject is ${#subject} chars; prefer <= 72" >&2
+fi
diff --git a/.runseal/hooks/pre-commit b/.runseal/hooks/pre-commit
new file mode 100644
index 0000000..1521564
--- /dev/null
+++ b/.runseal/hooks/pre-commit
@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+# runseal init hook: generated by runseal :init
+set -eu
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+
+runseal :guard
diff --git a/.runseal/wrappers/guard.seal b/.runseal/wrappers/guard.seal
new file mode 100644
index 0000000..cbda19f
--- /dev/null
+++ b/.runseal/wrappers/guard.seal
@@ -0,0 +1,195 @@
+print() {
+  printf '%s\n' "$1"
+}
+
+error() {
+  printf '%s\n' "$1" >&2
+}
+
+fail() {
+  error "$1"
+  exit 1
+}
+
+usage() {
+  print "Usage: runseal :guard [version-check|version-hash]"
+  print ""
+  print "Run repository guard checks or one explicit version-policy helper."
+  print ""
+  print "Commands:"
+  print "  version-check    validate version policy against stable metadata"
+  print "  version-hash     print the current guard.version.hash value"
+}
+
+mode=full
+if [ "$#" -gt 0 ]; then
+  case "$1" in
+    version-check)
+      mode=version-check
+      shift
+      ;;
+    version-hash)
+      mode=version-hash
+      shift
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "guard: unknown command: $1"
+      ;;
+  esac
+fi
+
+if [ "$#" -gt 0 ]; then
+  fail "guard: unexpected arguments"
+fi
+
+if [ "$mode" = version-hash ]; then
+  runseal @tool hash tree app/tests
+  exit 0
+fi
+
+public_url="${RUNSEAL_RELEASES_PUBLIC_URL:-}"
+if [ -z "$public_url" ]; then
+  public_url="https://releases.runseal.perish.uk"
+fi
+
+metadata_url="${RUNSEAL_STABLE_METADATA_URL:-}"
+if [ -z "$metadata_url" ]; then
+  metadata_url="$public_url/stable/latest/metadata.json"
+fi
+
+tmp_dir="${RUNSEAL_REPO_TMP_DIR:-.local/tmp}"
+if [ -n "${RUNNER_TEMP:-}" ]; then
+  tmp_dir="${RUNNER_TEMP}/runseal-guard"
+fi
+runseal @tool fs mkdir "$tmp_dir" 700
+metadata_file="$tmp_dir/runseal-guard-stable-metadata.json"
+cargo_metadata=$(cargo metadata --no-deps --format-version 1)
+current_version=$(runseal @tool json get "$cargo_metadata" '.packages[0].version')
+current_hash=$(runseal @tool hash tree app/tests)
+status=$(curl -sS -o "$metadata_file" -w "%{http_code}" "$metadata_url?version=$current_version")
+if [ "$status" = 404 ]; then
+  print "guard version policy: no stable metadata; skipping"
+  if [ "$mode" = version-check ]; then
+    exit 0
+  fi
+else
+  if [ "$status" = 200 ]; then
+  else
+    fail "guard version policy: failed to fetch stable metadata: HTTP $status"
+  fi
+
+  metadata=$(cat "$metadata_file")
+  has_prior_hash=$(runseal @tool json has "$metadata" .guard.version.hash)
+  if [ "$has_prior_hash" = true ]; then
+    prior_hash=$(runseal @tool json get "$metadata" .guard.version.hash)
+  else
+    prior_hash=
+  fi
+  if [ -z "$prior_hash" ]; then
+    print "guard version policy: stable metadata has no guard.version.hash; skipping"
+    if [ "$mode" = version-check ]; then
+      exit 0
+    fi
+  else
+    has_stable_version=$(runseal @tool json has "$metadata" .stableVersion)
+    if [ "$has_stable_version" = true ]; then
+      prior_version=$(runseal @tool json get "$metadata" .stableVersion)
+    else
+      prior_version=
+    fi
+    if [ -z "$prior_version" ]; then
+      has_release_version=$(runseal @tool json has "$metadata" .releaseVersion)
+      if [ "$has_release_version" = true ]; then
+      prior_version=$(runseal @tool json get "$metadata" .releaseVersion)
+      fi
+    fi
+    if [ -z "$prior_version" ]; then
+      fail "guard version policy: stable metadata is missing stableVersion/releaseVersion"
+    fi
+
+    current_order=$(runseal @tool version compare "$current_version" "$prior_version")
+    prior_major=$(runseal @tool version part "$prior_version" major)
+    prior_minor=$(runseal @tool version part "$prior_version" minor)
+    current_major=$(runseal @tool version part "$current_version" major)
+    current_minor=$(runseal @tool version part "$current_version" minor)
+    same_minor_lineage=false
+
+    if [ "$current_order" = lt ]; then
+      fail "guard version policy: version regressed below prior stable $prior_version"
+    fi
+    if [ "$current_order" = eq ]; then
+      fail "guard version policy: version matches prior stable $prior_version"
+    fi
+    if [ "$current_major" = "$prior_major" ]; then
+      if [ "$current_minor" = "$prior_minor" ]; then
+        same_minor_lineage=true
+      fi
+    fi
+
+    if [ "$current_hash" = "$prior_hash" ]; then
+      if [ "$same_minor_lineage" = false ]; then
+        fail "guard version policy: unchanged guard.version.hash requires a patch-only bump above $prior_version"
+      fi
+      print "guard version policy: hash unchanged -> patch bump ok ($prior_version -> $current_version)"
+    else
+      if [ "$same_minor_lineage" = true ]; then
+        fail "guard version policy: changed guard.version.hash requires a minor-or-higher bump above $prior_version"
+      fi
+      print "guard version policy: hash changed -> minor-or-higher bump ok ($prior_version -> $current_version)"
+    fi
+
+    if [ "$mode" = version-check ]; then
+      exit 0
+    fi
+  fi
+fi
+
+print "==> cargo fmt"
+cargo fmt --all --check
+
+print "==> cargo clippy"
+cargo clippy --locked --workspace --all-targets -- -D warnings
+
+print "==> cargo test"
+cargo test --locked --workspace
+
+print "==> seal wrappers"
+cargo run --quiet --locked -p runseal -- @transpile --input-lang=seal --output-lang=sealir .runseal/wrappers/cloudflare.seal
+cargo run --quiet --locked -p runseal -- @transpile --input-lang=seal --output-lang=sealir .runseal/wrappers/guard.seal
+cargo run --quiet --locked -p runseal -- @transpile --input-lang=seal --output-lang=sealir .runseal/wrappers/init.seal
+cargo run --quiet --locked -p runseal -- @transpile --input-lang=seal --output-lang=sealir .runseal/wrappers/pr.seal
+cargo run --quiet --locked -p runseal -- @transpile --input-lang=seal --output-lang=sealir .runseal/wrappers/release.seal
+
+print "==> flavor self-check"
+flavor check --root . --config flavor.toml
+
+print "==> shell syntax"
+sh -n manage.sh
+sh -n .github/scripts/release/assets/checksums.sh
+sh -n .github/scripts/release/assets/package.sh
+sh -n .github/scripts/release/assets/verify.sh
+sh -n .github/scripts/release/github/cleanup-artifacts.sh
+bash -n .github/scripts/release/r2/check.sh
+bash -n .github/scripts/release/r2/publish.sh
+bash -n .github/scripts/release/r2/summary.sh
+bash -n .github/scripts/release/r2/verify.sh
+sh -n .github/scripts/release/smoke/smoke.sh
+
+print "==> python syntax"
+python3 -m py_compile .github/scripts/release/metadata/beta.py
+python3 -m py_compile .github/scripts/release/metadata/stable.py
+
+has_pwsh=$(runseal @tool process exists pwsh)
+if [ "$has_pwsh" = true ]; then
+  print "==> PowerShell syntax"
+  pwsh -NoProfile -NonInteractive -Command "[scriptblock]::Create((Get-Content -Raw 'manage.ps1')) | Out-Null"
+  pwsh -NoProfile -NonInteractive -Command "[scriptblock]::Create((Get-Content -Raw '.github/scripts/release/assets/package.ps1')) | Out-Null"
+  pwsh -NoProfile -NonInteractive -Command "[scriptblock]::Create((Get-Content -Raw '.github/scripts/release/smoke/smoke.ps1')) | Out-Null"
+else
+  print "==> PowerShell syntax"
+  print "skip: pwsh not found"
+fi
diff --git a/.runseal/wrappers/init.seal b/.runseal/wrappers/init.seal
index cfc7cfb..904da5e 100644
--- a/.runseal/wrappers/init.seal
+++ b/.runseal/wrappers/init.seal
@@ -93,9 +93,10 @@ require_tool runseal
 require_tool flavor
 require_tool sh
 require_tool bash
+require_tool cp
 require_tool sed
 require_tool grep
-print "ok: git, python3, cargo, runseal, flavor, sh, bash, sed, grep"
+print "ok: git, python3, cargo, runseal, flavor, sh, bash, cp, sed, grep"
 
 print "==> checking repository entrypoints"
 require_path Cargo.toml
@@ -104,7 +105,10 @@ require_path flavor.toml
 require_path manage.sh
 require_path manage.ps1
 require_path runseal.toml
+require_path .runseal/hooks/pre-commit
+require_path .runseal/hooks/commit-msg
 require_path .runseal/wrappers/cloudflare.seal
+require_path .runseal/wrappers/guard.seal
 require_path .runseal/wrappers/init.seal
 require_path .runseal/wrappers/pr.seal
 require_path .runseal/wrappers/release.seal
@@ -123,13 +127,13 @@ runseal @tool fs mkdir "$hooks_dir" 700
 
 prepare_hook "$pre_commit"
 
-runseal @tool fs write-base64 "$pre_commit" IyEvdXNyL2Jpbi9lbnYgc2gKIyBydW5zZWFsIGluaXQgaG9vazogZ2VuZXJhdGVkIGJ5IC5ydW5zZWFsL3dyYXBwZXJzL2luaXQuc2VhbApzZXQgLWV1CnJvb3Q9JChnaXQgcmV2LXBhcnNlIC0tc2hvdy10b3BsZXZlbCkKY2QgIiRyb290IgoKZWNobyAiPT0+IGNhcmdvIGZtdCIKY2FyZ28gZm10IC0tYWxsIC0tY2hlY2sKCmVjaG8gIj09PiBjYXJnbyBjbGlwcHkiCmNhcmdvIGNsaXBweSAtLWxvY2tlZCAtLXdvcmtzcGFjZSAtLWFsbC10YXJnZXRzIC0tIC1EIHdhcm5pbmdzCgplY2hvICI9PT4gY2FyZ28gdGVzdCIKY2FyZ28gdGVzdCAtLWxvY2tlZCAtLXdvcmtzcGFjZQoKZWNobyAiPT0+IHNlYWwgd3JhcHBlcnMiCmNhcmdvIHJ1biAtLXF1aWV0IC0tbG9ja2VkIC1wIHJ1bnNlYWwgLS0gQHRyYW5zcGlsZSAtLWlucHV0LWxhbmc9c2VhbCAtLW91dHB1dC1sYW5nPXNlYWxpciAucnVuc2VhbC93cmFwcGVycy9pbml0LnNlYWwgPi9kZXYvbnVsbApjYXJnbyBydW4gLS1xdWlldCAtLWxvY2tlZCAtcCBydW5zZWFsIC0tIEB0cmFuc3BpbGUgLS1pbnB1dC1sYW5nPXNlYWwgLS1vdXRwdXQtbGFuZz1zZWFsaXIgLnJ1bnNlYWwvd3JhcHBlcnMvY2xvdWRmbGFyZS5zZWFsID4vZGV2L251bGwKY2FyZ28gcnVuIC0tcXVpZXQgLS1sb2NrZWQgLXAgcnVuc2VhbCAtLSBAdHJhbnNwaWxlIC0taW5wdXQtbGFuZz1zZWFsIC0tb3V0cHV0LWxhbmc9c2VhbGlyIC5ydW5zZWFsL3dyYXBwZXJzL3ByLnNlYWwgPi9kZXYvbnVsbApjYXJnbyBydW4gLS1xdWlldCAtLWxvY2tlZCAtcCBydW5zZWFsIC0tIEB0cmFuc3BpbGUgLS1pbnB1dC1sYW5nPXNlYWwgLS1vdXRwdXQtbGFuZz1zZWFsaXIgLnJ1bnNlYWwvd3JhcHBlcnMvcmVsZWFzZS5zZWFsID4vZGV2L251bGwKCmVjaG8gIj09PiBmbGF2b3Igc2VsZi1jaGVjayIKZmxhdm9yIGNoZWNrIC0tcm9vdCAuIC0tY29uZmlnIGZsYXZvci50b21sCgplY2hvICI9PT4gc2hlbGwgc3ludGF4IgpzaCAtbiBtYW5hZ2Uuc2gKc2ggLW4gLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2UvYXNzZXRzL2NoZWNrc3Vtcy5zaApzaCAtbiAuZ2l0aHViL3NjcmlwdHMvcmVsZWFzZS9hc3NldHMvcGFja2FnZS5zaApzaCAtbiAuZ2l0aHViL3NjcmlwdHMvcmVsZWFzZS9hc3NldHMvdmVyaWZ5LnNoCnNoIC1uIC5naXRodWIvc2NyaXB0cy9yZWxlYXNlL2dpdGh1Yi9jbGVhbnVwLWFydGlmYWN0cy5zaApiYXNoIC1uIC5naXRodWIvc2NyaXB0cy9yZWxlYXNlL3IyL2NoZWNrLnNoCmJhc2ggLW4gLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2UvcjIvcHVibGlzaC5zaApiYXNoIC1uIC5naXRodWIvc2NyaXB0cy9yZWxlYXNlL3IyL3N1bW1hcnkuc2gKYmFzaCAtbiAuZ2l0aHViL3NjcmlwdHMvcmVsZWFzZS9yMi92ZXJpZnkuc2gKc2ggLW4gLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2Uvc21va2Uvc21va2Uuc2gKCmVjaG8gIj09PiBweXRob24gc3ludGF4IgpweXRob24zIC1tIHB5X2NvbXBpbGUgLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2UvbWV0YWRhdGEvYmV0YS5weQpweXRob24zIC1tIHB5X2NvbXBpbGUgLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2UvbWV0YWRhdGEvc3RhYmxlLnB5CgppZiBjb21tYW5kIC12IHB3c2ggPi9kZXYvbnVsbCAyPiYxOyB0aGVuCiAgZWNobyAiPT0+IFBvd2VyU2hlbGwgc3ludGF4IgogIHB3c2ggLU5vUHJvZmlsZSAtTm9uSW50ZXJhY3RpdmUgLUNvbW1hbmQgICAgICcKJEVycm9yQWN0aW9uUHJlZmVyZW5jZSA9ICJTdG9wIgokcGF0aHMgPSBAKAogICJtYW5hZ2UucHMxIiwKICAiLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2UvYXNzZXRzL3BhY2thZ2UucHMxIiwKICAiLmdpdGh1Yi9zY3JpcHRzL3JlbGVhc2Uvc21va2Uvc21va2UucHMxIgopCmZvcmVhY2ggKCRwYXRoIGluICRwYXRocykgewogIFtzY3JpcHRibG9ja106OkNyZWF0ZSgoR2V0LUNvbnRlbnQgLVJhdyAkcGF0aCkpIHwgT3V0LU51bGwKfQonCmVsc2UKICBlY2hvICI9PT4gUG93ZXJTaGVsbCBzeW50YXgiCiAgZWNobyAic2tpcDogcHdzaCBub3QgZm91bmQiCmZp
+cp .runseal/hooks/pre-commit "$pre_commit"
 runseal @tool fs chmod "$pre_commit" 755
 print "installed $pre_commit"
 
 prepare_hook "$commit_msg"
 
-runseal @tool fs write-base64 "$commit_msg" IyEvdXNyL2Jpbi9lbnYgc2gKIyBydW5zZWFsIGluaXQgaG9vazogZ2VuZXJhdGVkIGJ5IC5ydW5zZWFsL3dyYXBwZXJzL2luaXQuc2VhbApzZXQgLWV1CgppZiBbICIkIyIgLW5lIDEgXSB8fCBbICEgLWYgIiQxIiBdOyB0aGVuCiAgZWNobyAiY29tbWl0IG1lc3NhZ2UgZmlsZSBub3QgZm91bmQiID4mMgogIGV4aXQgMQpmaQoKc3ViamVjdD0kKHNlZCAtbiAnCi9eW1s6c3BhY2U6XV0qIy9kCi9bXls6c3BhY2U6XV0vIHsKICBzL15bWzpzcGFjZTpdXSovLwogIHMvW1s6c3BhY2U6XV0qJC8vCiAgcAogIHEKfQonICIkMSIpCgppZiBbIC16ICIkc3ViamVjdCIgXTsgdGhlbgogIGVjaG8gImNvbW1pdCBzdWJqZWN0IGlzIGVtcHR5IiA+JjIKICBleGl0IDEKZmkKCmNhc2UgIiRzdWJqZWN0IiBpbgogICJNZXJnZSAiKnwiUmV2ZXJ0ICIqfCJmaXh1cCEiKnwic3F1YXNoISIqKQogICAgZXhpdCAwCiAgICA7Owplc2FjCgppZiAhIHByaW50ZiAnJXMKJyAiJHN1YmplY3QiIHwgZ3JlcCAtRXEgJ15bYS16XVthLXowLTktXSooL1thLXowLTktXSspKjogW15bOnNwYWNlOl1dLionOyB0aGVuCiAgZWNobyAiY29tbWl0IHN1YmplY3QgbXVzdCBsb29rIGxpa2UgJzxhcmVhPjogPGltcGVyYXRpdmUgc3VtbWFyeT4nIiA+JjIKICBlY2hvICJhY3R1YWw6ICRzdWJqZWN0IiA+JjIKICBleGl0IDEKZmkKCmlmIFsgIiR7I3N1YmplY3R9IiAtZ3QgNzIgXTsgdGhlbgogIGVjaG8gIndhcm5pbmc6IGNvbW1pdCBzdWJqZWN0IGlzICR7I3N1YmplY3R9IGNoYXJzOyBwcmVmZXIgPD0gNzIiID4mMgpmaQo=
+cp .runseal/hooks/commit-msg "$commit_msg"
 runseal @tool fs chmod "$commit_msg" 755
 print "installed $commit_msg"
 
diff --git a/AGENTS.md b/AGENTS.md
index 4b47e32..b911150 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,7 +17,22 @@ This top-level `AGENTS.md` is the repository navigation and policy layer.
 
 Core product stance:
 
-- Small CLI. Explicit profile. No hidden orchestration.
+- `runseal` is not just an operations toolkit. It is an operations methodology
+  plus a derived tool system: the main value is deciding which operational
+  complexity belongs in wrappers, atomic tools, repo/local artifacts, or
+  external scripts, then keeping those layers explicit.
+- `runseal` exists to reduce environment-dependency complexity in real
+  cross-platform operations work: too many environment variables, too many
+  machine-specific assumptions, and too much operational glue falling back to
+  Python or JavaScript even when the underlying workflow is clear and finite.
+- Explicit profile. No hidden orchestration.
+- Prefer a stable shared subset of `bash` and PowerShell for `.seal`, plus
+  explicit atomic `@tool` capabilities for needs that do not fit that shared
+  shell surface cleanly.
+- Preserve cross-shell semantic equivalence as the hard constraint. Do not
+  require local syntax symmetry or IR-level elegance when a `.seal` behavior is
+  still clear, finite, and can be translated reliably into a more awkward
+  PowerShell form.
 - Keep the Rust core thin and concrete.
 - Support only `env`, `symlink`, fixed-prefix `argv`, explicit `:wrapper`
   resolution, direct `.seal` execution, and read-only `@internal`
@@ -142,11 +157,52 @@ Successful profile and wrapper paths are normalized absolute paths.
 
 ## 5. FAQ
 
-### Why keep the CLI surface small?
+### What defines the CLI surface?
 
-Because this repository is building explicit runtime glue, not a hidden
-orchestrator. New behavior should be added only when it fits the existing
-surface cleanly.
+This repository is building explicit runtime glue, not a hidden orchestrator.
+New behavior should be added only when it fits one of two shapes cleanly:
+
+- shared `bash` and PowerShell semantics that are worth making first-class in
+  `.seal`
+- an explicit atomic `@tool`
+
+`runseal` should not be treated as a grab-bag operations toolkit where every
+pain point becomes another command. Its value is methodological first:
+
+- decide what should be flow control in `.seal`
+- decide what should be an atomic `@tool`
+- decide what should be a visible repo or local artifact under `.runseal/` or
+  `.local/`
+- decide what should remain an external script because it carries the wrong
+  kind of complexity
+
+The concrete tools matter, but they are derived from that layering model rather
+than the other way around.
+
+This boundary comes from the actual problem `runseal` is trying to solve:
+clear operational workflows should not need to depend on heavyweight language
+runtimes or repository-local script stacks just to survive environment drift,
+cross-platform differences, and routine operator setup friction.
+
+The goal is not "be as small as possible". The goal is to absorb the
+right kind of complexity:
+
+- clear, finite, cross-platform operational flow control should fit in
+  `runseal`
+- shell-specific cleverness, open-ended scripting power, and accidental runtime
+  dependency sprawl should not
+
+That is why the product boundary is a shared shell subset plus explicit atomic
+tools, rather than a general scripting platform or a partial shell clone.
+
+The hard promise is behavioral equivalence across `bash` and PowerShell, not
+surface-level symmetry in generated code. Some worthwhile `.seal` semantics may
+compile into elegant `bash` and relatively ugly PowerShell. That tradeoff is
+acceptable when:
+
+- the `.seal` behavior is clear and finite
+- the translation is reliable and testable
+- the result still serves explicit cross-platform operations flow control
 
 ### When should behavior become Seal syntax?
 
@@ -156,14 +212,42 @@ worth making first-class.
 ### When should behavior become `@tool`?
 
 When native CLI coverage is insufficient for an atomic, reusable operation and
-the result still fits the small explicit model.
+the result still fits the explicit atomic-tool model.
 
 ### When should logic stay outside runseal?
 
 When the behavior cannot be described cleanly as shared shell-shape syntax or a
-small atomic tool, keep it in Python, Ruby, JavaScript, or another external
+clear atomic tool, keep it in Python, Ruby, JavaScript, or another external
 script.
 
+### Should `.seal` wrappers build multi-line config or payload text inline?
+
+Usually no.
+
+For operations work, persistent or semi-persistent structured text should
+normally live as explicit repo material under `.runseal/` or `.local/`, not as
+inline heredoc-style wrapper content. That includes things like:
+
+- config templates
+- YAML or JSON fragments
+- kube-related files
+- long request bodies
+- other operator-facing text payloads
+
+The wrapper should usually do the smaller, clearer job:
+
+- validate preconditions
+- choose the right file or template
+- assemble paths and arguments
+- set environment for the invoked command
+- execute the operational flow
+
+This is an intentional product boundary. `runseal` is meant to reduce
+environment and runtime dependency complexity in operations workflows, not to
+turn `.seal` into a general inline text-construction language. If a multi-line
+artifact is important enough to exist, prefer making it a visible repo or local
+artifact first.
+
 ### Should `.seal` wrappers be treated as first-class runtime entrypoints?
 
 Yes. Treat `.runseal/wrappers/*.seal` as first-class wrappers executed directly
diff --git a/Cargo.lock b/Cargo.lock
index a5514f0..818af29 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -100,6 +100,15 @@ version = "2.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "84d7ced0ae9557296835c32bf1b1e02b44c746701f898460fb000d7eaa84f00a"
 
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "bstr"
 version = "1.12.1"
@@ -191,12 +200,41 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
 [[package]]
 name = "difflib"
 version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
@@ -321,6 +359,16 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -1012,7 +1060,7 @@ dependencies = [
 
 [[package]]
 name = "runseal"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -1023,6 +1071,7 @@ dependencies = [
  "reqwest",
  "serde",
  "serde_json",
+ "sha2",
  "shellexpand",
  "tempfile",
  "toml",
@@ -1165,6 +1214,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "shellexpand"
 version = "3.1.2"
@@ -1450,6 +1510,12 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -1492,6 +1558,12 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
 [[package]]
 name = "wait-timeout"
 version = "0.2.1"
diff --git a/README.md b/README.md
index f0f7a26..ddf3d86 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,17 @@ runseal --profile ./runseal.toml bash -lc 'echo "$RUNSEAL_PROFILE_PATH"'
 
 Use `runseal profile` without `@` to run an external command named `profile`.
 
+## Examples
+
+Repository-owned examples for canonical `.seal` and `@tool` shapes live under
+[docs/examples](./docs/examples/README.md).
+
+Start here when a wrapper shape feels "obvious in shell" but still needs the
+exact runseal form:
+
+- [Seal `case` / argv parser shapes](./docs/examples/seal/case.md)
+- [GitHub tool examples](./docs/examples/tools/github.md)
+
 ## Fit
 
 Fits well:
@@ -272,22 +283,21 @@ round trips. For example, a wrapper can expose `:ssh <host> --run <script>`
 while `runseal @tool ssh script run` owns the stdin, argv forwarding, and host
 config details.
 
-For example:
+For example, a repo-local `:kube` wrapper can stay pure `.seal` by pushing file
+enumeration and path joining into atomic tools:
 
 ```bash
-fail() {
-  printf '%s\n' "$1" >&2
-  exit 1
-}
-
-if [ -z "$channel" ]; then
-  fail "channel missing"
-fi
-
-raw=$(gh run list --json databaseId)
-run_id=$(runseal @tool json get "$raw" '.[0].databaseId')
+kube_dir=${PERISH_TOP_KUBE_DIR:?kube: missing PERISH_TOP_KUBE_DIR}
+configs=$(runseal @tool fs list "$kube_dir" --glob "*.yaml" --files --require-nonempty)
+kubeconfig=$(runseal @tool string join "$configs" --separator path)
+KUBECONFIG="$kubeconfig" kubectl "$@"
 ```
 
+Prefer visible repo or local artifacts under `.runseal/` or `.local/` for
+multi-line config and payload text. The wrapper should usually validate
+preconditions, choose files, assemble arguments, and invoke the operational
+flow, rather than build inline heredoc-style configuration.
+
 Runseal interprets `.seal` wrappers directly when called as `runseal :name`.
 Use `runseal @transpile --input-lang=seal --output-lang=bash <file>` or
 `--output-lang=powershell` to inspect generated targets.
diff --git a/app/Cargo.toml b/app/Cargo.toml
index 19c286c..bb7b4a3 100644
--- a/app/Cargo.toml
+++ b/app/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "runseal"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2024"
 
 [dependencies]
@@ -15,6 +15,7 @@ toml = "0.8"
 yaml_serde = "0.10"
 tempfile = "3.12"
 base64 = "0.22"
+sha2 = "0.10"
 reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
 
 [dev-dependencies]
diff --git a/app/src/core/tool/gitee/mod.rs b/app/src/core/tool/gitee/mod.rs
index 51844f2..f8b5dc2 100644
--- a/app/src/core/tool/gitee/mod.rs
+++ b/app/src/core/tool/gitee/mod.rs
@@ -34,13 +34,61 @@ fn repo_parse_origin(args: &[String]) -> Result<Option<String>> {
 
 fn pr(args: &[String]) -> Result<Option<String>> {
     let [command, rest @ ..] = args else {
-        bail!("usage: runseal @tool gitee pr create|pass-gates|merge ...");
+        bail!("usage: runseal @tool gitee pr find|create|pass-gates|merge ...");
     };
     match command.as_str() {
+        "find" => pr_find(rest),
         "create" => pr_create(rest),
         "pass-gates" => pr_pass_gates(rest),
         "merge" => pr_merge(rest),
-        _ => bail!("usage: runseal @tool gitee pr create|pass-gates|merge ..."),
+        _ => bail!("usage: runseal @tool gitee pr find|create|pass-gates|merge ..."),
+    }
+}
+
+fn pr_find(args: &[String]) -> Result<Option<String>> {
+    let owner = required_option(args, "--owner")?;
+    let repo = required_option(args, "--repo")?;
+    let token = token(args)?;
+    let head = required_option(args, "--head")?;
+    let base = optional_option(args, "--base");
+    let state = optional_option(args, "--state").unwrap_or_else(|| "open".to_string());
+    if !matches!(state.as_str(), "open" | "merged" | "closed" | "all") {
+        bail!("--state must be one of: open, merged, closed, all");
+    }
+
+    let mut query = vec![
+        ("head".to_string(), head.clone()),
+        ("state".to_string(), state),
+    ];
+    if let Some(base) = &base {
+        query.push(("base".to_string(), base.clone()));
+    }
+
+    let raw = request_json(
+        "GET",
+        &format!("/repos/{owner}/{repo}/pulls"),
+        &token,
+        None,
+        &query,
+    )?;
+    let Some(items) = raw.as_array() else {
+        bail!("Gitee API returned non-array JSON for pull request listing");
+    };
+
+    let matches = items
+        .iter()
+        .filter(|item| pr_matches(item, &head, base.as_deref()))
+        .cloned()
+        .collect::<Vec<_>>();
+    match matches.len() {
+        0 => Ok(Some("null".to_string())),
+        1 => Ok(Some(serde_json::to_string(&matches[0])?)),
+        count => bail!(
+            "Gitee PR find is ambiguous for head `{head}`{}: found {count} matches",
+            base.as_deref()
+                .map(|value| format!(" and base `{value}`"))
+                .unwrap_or_default()
+        ),
     }
 }
 
@@ -100,14 +148,18 @@ fn pr_merge(args: &[String]) -> Result<Option<String>> {
     )
 }
 
-fn request(method: &str, path: &str, token: &str, mut body: JsonValue) -> Result<Option<String>> {
-    let Some(object) = body.as_object_mut() else {
-        bail!("Gitee request body must be a JSON object");
-    };
-    object.insert(
-        "access_token".to_string(),
-        JsonValue::String(token.to_string()),
-    );
+fn request(method: &str, path: &str, token: &str, body: JsonValue) -> Result<Option<String>> {
+    let payload = request_json(method, path, token, Some(body), &[])?;
+    Ok(Some(serde_json::to_string(&payload)?))
+}
+
+fn request_json(
+    method: &str,
+    path: &str,
+    token: &str,
+    body: Option<JsonValue>,
+    query: &[(String, String)],
+) -> Result<JsonValue> {
     let base = std::env::var("RUNSEAL_GITEE_API_BASE")
         .unwrap_or_else(|_| "https://gitee.com/api/v5".to_string());
     let path = if path.starts_with('/') {
@@ -122,14 +174,33 @@ fn request(method: &str, path: &str, token: &str, mut body: JsonValue) -> Result
     let method = method
         .parse::<reqwest::Method>()
         .with_context(|| format!("invalid HTTP method: {method}"))?;
-    let response = client
-        .request(method.clone(), &url)
-        .header(reqwest::header::ACCEPT, "application/json")
-        .header(reqwest::header::CONTENT_TYPE, "application/json")
-        .header(reqwest::header::AUTHORIZATION, format!("token {token}"))
-        .json(&body)
-        .send()
-        .with_context(|| format!("Gitee API {method} {path} unreachable"))?;
+    let response = if let Some(mut body) = body {
+        let Some(object) = body.as_object_mut() else {
+            bail!("Gitee request body must be a JSON object");
+        };
+        object.insert(
+            "access_token".to_string(),
+            JsonValue::String(token.to_string()),
+        );
+        client
+            .request(method.clone(), &url)
+            .header(reqwest::header::ACCEPT, "application/json")
+            .header(reqwest::header::CONTENT_TYPE, "application/json")
+            .header(reqwest::header::AUTHORIZATION, format!("token {token}"))
+            .query(query)
+            .json(&body)
+            .send()
+            .with_context(|| format!("Gitee API {method} {path} unreachable"))?
+    } else {
+        client
+            .request(method.clone(), &url)
+            .header(reqwest::header::ACCEPT, "application/json")
+            .header(reqwest::header::CONTENT_TYPE, "application/json")
+            .header(reqwest::header::AUTHORIZATION, format!("token {token}"))
+            .query(query)
+            .send()
+            .with_context(|| format!("Gitee API {method} {path} unreachable"))?
+    };
     let status = response.status();
     let raw = response
         .text()
@@ -137,13 +208,40 @@ fn request(method: &str, path: &str, token: &str, mut body: JsonValue) -> Result
     if !status.is_success() {
         bail!("Gitee API {method} {path} -> {}: {raw}", status.as_u16());
     }
-    let payload: JsonValue = if raw.trim().is_empty() {
-        JsonValue::Object(Default::default())
-    } else {
-        serde_json::from_str(&raw)
-            .with_context(|| format!("Gitee API returned invalid JSON for {path}"))?
+    if raw.trim().is_empty() {
+        return Ok(JsonValue::Object(Default::default()));
+    }
+    serde_json::from_str(&raw)
+        .with_context(|| format!("Gitee API returned invalid JSON for {path}"))
+}
+
+fn pr_matches(item: &JsonValue, head: &str, base: Option<&str>) -> bool {
+    let Some(item_head) = pr_head_branch(item) else {
+        return false;
     };
-    Ok(Some(serde_json::to_string(&payload)?))
+    if item_head != head {
+        return false;
+    }
+    match base {
+        Some(expected) => pr_base_branch(item).is_some_and(|value| value == expected),
+        None => true,
+    }
+}
+
+fn pr_head_branch(item: &JsonValue) -> Option<&str> {
+    item.get("head")
+        .and_then(|value| value.get("ref").or_else(|| value.get("label")))
+        .and_then(JsonValue::as_str)
+        .or_else(|| item.get("head").and_then(JsonValue::as_str))
+        .map(|value| value.rsplit(':').next().unwrap_or(value))
+}
+
+fn pr_base_branch(item: &JsonValue) -> Option<&str> {
+    item.get("base")
+        .and_then(|value| value.get("ref").or_else(|| value.get("label")))
+        .and_then(JsonValue::as_str)
+        .or_else(|| item.get("base").and_then(JsonValue::as_str))
+        .map(|value| value.rsplit(':').next().unwrap_or(value))
 }
 
 fn token(args: &[String]) -> Result<String> {
@@ -159,12 +257,20 @@ fn token(args: &[String]) -> Result<String> {
         }
         bail!("GITEE_TOKEN not set in {path}");
     }
+    if let Some(name) = optional_option(args, "--token-env") {
+        let token = std::env::var(&name)
+            .with_context(|| format!("environment variable not set: {name}"))?;
+        if token.is_empty() {
+            bail!("environment variable is empty: {name}");
+        }
+        return Ok(token);
+    }
     if let Ok(token) = std::env::var("GITEE_TOKEN")
         && !token.is_empty()
     {
         return Ok(token);
     }
-    bail!("missing Gitee token: pass --token, --token-file, or set GITEE_TOKEN")
+    bail!("missing Gitee token: pass --token, --token-file, --token-env, or set GITEE_TOKEN")
 }
 
 fn parse_env_file(path: &Path) -> Result<BTreeMap<String, String>> {
diff --git a/app/src/core/tool/github.rs b/app/src/core/tool/github.rs
deleted file mode 100644
index d41c4b9..0000000
--- a/app/src/core/tool/github.rs
+++ /dev/null
@@ -1,35 +0,0 @@
-use std::process::Command;
-
-use anyhow::{Context, Result, bail};
-
-pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
-    match (command, args) {
-        ("pr", [checks, probe, number]) if checks == "checks" && probe == "probe" => {
-            pr_checks_probe(number)
-        }
-        _ => bail!("unknown tool command: github {command}"),
-    }
-}
-
-fn pr_checks_probe(number: &str) -> Result<Option<String>> {
-    let output = Command::new("gh")
-        .args(["pr", "checks", number])
-        .output()
-        .with_context(|| "failed to execute command: gh")?;
-    let combined = format!(
-        "{}{}",
-        String::from_utf8_lossy(&output.stdout),
-        String::from_utf8_lossy(&output.stderr)
-    );
-    if combined.contains("no checks reported") {
-        return Ok(Some("false".to_string()));
-    }
-    if output.status.success() {
-        return Ok(Some("true".to_string()));
-    }
-    bail!(
-        "gh pr checks failed with status {}: {}",
-        output.status.code().unwrap_or(1),
-        combined.trim()
-    );
-}
diff --git a/app/src/core/tool/github/mod.rs b/app/src/core/tool/github/mod.rs
new file mode 100644
index 0000000..bdd7e71
--- /dev/null
+++ b/app/src/core/tool/github/mod.rs
@@ -0,0 +1,211 @@
+mod support;
+
+use anyhow::{Result, bail};
+use serde_json::Value as JsonValue;
+
+use self::support::{
+    core_repo_contains, current_branch, current_github_repo_id, current_repo_id, github_request,
+    github_request_text, optional_token, prefix_enabled, read_body, token, validate_body_max,
+};
+
+pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
+    match command {
+        "issue" => issue(args),
+        "pr" => pr(args),
+        _ => bail!("unknown tool command: github {command}"),
+    }
+}
+
+fn issue(args: &[String]) -> Result<Option<String>> {
+    let [command, rest @ ..] = args else {
+        bail!("usage: runseal @tool github issue create|comment|body ...");
+    };
+    match command.as_str() {
+        "create" => issue_create(rest),
+        "comment" => issue_comment(rest),
+        "body" => issue_body(rest),
+        _ => bail!("usage: runseal @tool github issue create|comment|body ..."),
+    }
+}
+
+fn pr(args: &[String]) -> Result<Option<String>> {
+    let [command, rest @ ..] = args else {
+        bail!("usage: runseal @tool github pr checks probe <number>");
+    };
+    match command.as_str() {
+        "checks" => pr_checks(rest),
+        _ => bail!("usage: runseal @tool github pr checks probe <number>"),
+    }
+}
+
+fn pr_checks(args: &[String]) -> Result<Option<String>> {
+    let [command, rest @ ..] = args else {
+        bail!("usage: runseal @tool github pr checks probe <number>");
+    };
+    match command.as_str() {
+        "probe" => pr_checks_probe(rest),
+        _ => bail!("usage: runseal @tool github pr checks probe <number>"),
+    }
+}
+
+fn pr_checks_probe(args: &[String]) -> Result<Option<String>> {
+    let [number] = args else {
+        bail!("usage: runseal @tool github pr checks probe <number>");
+    };
+    match pr_checks_probe_http(number, args) {
+        Ok(value) => Ok(Some(value)),
+        Err(_) => Ok(Some("true".to_string())),
+    }
+}
+
+fn pr_checks_probe_http(number: &str, args: &[String]) -> Result<String> {
+    let current_repo = current_github_repo_id()?;
+    let token = optional_token(args)?;
+    let pr: JsonValue = github_request(
+        "GET",
+        &format!("/repos/{current_repo}/pulls/{number}"),
+        token.as_deref(),
+        None,
+    )?;
+    let Some(sha) = pr
+        .get("head")
+        .and_then(|value| value.get("sha"))
+        .and_then(JsonValue::as_str)
+    else {
+        bail!("GitHub API pull request payload missing head.sha");
+    };
+    let checks: JsonValue = github_request(
+        "GET",
+        &format!("/repos/{current_repo}/commits/{sha}/check-runs"),
+        token.as_deref(),
+        None,
+    )?;
+    let statuses: JsonValue = github_request(
+        "GET",
+        &format!("/repos/{current_repo}/commits/{sha}/status"),
+        token.as_deref(),
+        None,
+    )?;
+    let check_runs = checks
+        .get("total_count")
+        .and_then(JsonValue::as_u64)
+        .unwrap_or(0);
+    let status_count = statuses
+        .get("statuses")
+        .and_then(JsonValue::as_array)
+        .map(|value| value.len())
+        .unwrap_or(0);
+    Ok(if check_runs > 0 || status_count > 0 {
+        "true"
+    } else {
+        "false"
+    }
+    .to_string())
+}
+
+fn issue_comment(args: &[String]) -> Result<Option<String>> {
+    let [command, rest @ ..] = args else {
+        bail!("usage: runseal @tool github issue comment create ...");
+    };
+    match command.as_str() {
+        "create" => issue_comment_create(rest),
+        _ => bail!("usage: runseal @tool github issue comment create ..."),
+    }
+}
+
+fn issue_create(args: &[String]) -> Result<Option<String>> {
+    let repo = support::required_option(args, "--repo")?;
+    let title = support::required_option(args, "--title")?;
+    let token = token(args)?;
+    let body = optional_prepared_body(args, &repo, 0)?;
+    let mut payload = serde_json::Map::new();
+    payload.insert("title".to_string(), serde_json::Value::String(title));
+    if let Some(body) = body {
+        payload.insert("body".to_string(), serde_json::Value::String(body));
+    }
+    github_request(
+        "POST",
+        &format!("/repos/{repo}/issues"),
+        Some(&token),
+        Some(serde_json::Value::Object(payload)),
+    )
+    .map(|payload| Some(serde_json::to_string(&payload).expect("GitHub payload should serialize")))
+}
+
+fn issue_body(args: &[String]) -> Result<Option<String>> {
+    let [command, rest @ ..] = args else {
+        bail!("usage: runseal @tool github issue body update ...");
+    };
+    match command.as_str() {
+        "update" => issue_body_update(rest),
+        _ => bail!("usage: runseal @tool github issue body update ..."),
+    }
+}
+
+fn issue_comment_create(args: &[String]) -> Result<Option<String>> {
+    let repo = support::required_option(args, "--repo")?;
+    let number = support::required_option(args, "--number")?;
+    let token = token(args)?;
+    let body = prepared_body(args, &repo, 100)?;
+    github_request_text(
+        "POST",
+        &format!("/repos/{repo}/issues/{number}/comments"),
+        &token,
+        body,
+    )
+}
+
+fn issue_body_update(args: &[String]) -> Result<Option<String>> {
+    let repo = support::required_option(args, "--repo")?;
+    let number = support::required_option(args, "--number")?;
+    let token = token(args)?;
+    let body = prepared_body(args, &repo, 0)?;
+    github_request_text(
+        "PATCH",
+        &format!("/repos/{repo}/issues/{number}"),
+        &token,
+        body,
+    )
+}
+
+fn prepared_body(args: &[String], target_repo: &str, default_body_max: usize) -> Result<String> {
+    let mut body = read_body(args)?;
+    validate_body_max(args, &body, default_body_max)?;
+    if prefix_enabled(args)? {
+        body = prefix_body(target_repo, &body)?;
+    }
+    Ok(body)
+}
+
+fn optional_prepared_body(
+    args: &[String],
+    target_repo: &str,
+    default_body_max: usize,
+) -> Result<Option<String>> {
+    let has_body = args
+        .iter()
+        .any(|arg| arg == "--body" || arg.starts_with("--body="));
+    let has_body_file = args
+        .iter()
+        .any(|arg| arg == "--body-file" || arg.starts_with("--body-file="));
+    match (has_body, has_body_file) {
+        (false, false) => Ok(None),
+        _ => prepared_body(args, target_repo, default_body_max).map(Some),
+    }
+}
+
+fn prefix_body(target_repo: &str, body: &str) -> Result<String> {
+    if !core_repo_contains(target_repo) {
+        return Ok(body.to_string());
+    }
+    let current_repo = current_repo_id()?;
+    if current_repo.eq_ignore_ascii_case(target_repo) {
+        return Ok(body.to_string());
+    }
+    let branch = current_branch()?;
+    let prefix = format!("Requested-By-Repo: {current_repo}\nRequested-By-Branch: {branch}\n\n");
+    if body.starts_with(&prefix) {
+        return Ok(body.to_string());
+    }
+    Ok(format!("{prefix}{body}"))
+}
diff --git a/app/src/core/tool/github/support.rs b/app/src/core/tool/github/support.rs
new file mode 100644
index 0000000..577981b
--- /dev/null
+++ b/app/src/core/tool/github/support.rs
@@ -0,0 +1,347 @@
+use std::{collections::BTreeMap, path::Path, process::Command, time::Duration};
+
+use anyhow::{Context, Result, bail};
+use serde_json::Value as JsonValue;
+
+const GITHUB_API_BASE: &str = "https://api.github.com";
+const GITHUB_API_VERSION: &str = "2022-11-28";
+const CORE_REPOS: &[&str] = &[
+    "PerishCode/flavor",
+    "PerishCode/runseal",
+    "PerishCode/sidecar",
+];
+
+pub fn github_request_text(
+    method: &str,
+    path: &str,
+    token: &str,
+    body: String,
+) -> Result<Option<String>> {
+    github_request(
+        method,
+        path,
+        Some(token),
+        Some(serde_json::json!({
+            "body": body,
+        })),
+    )
+    .map(|payload| Some(serde_json::to_string(&payload).expect("GitHub payload should serialize")))
+}
+
+pub fn github_request(
+    method: &str,
+    path: &str,
+    token: Option<&str>,
+    body: Option<JsonValue>,
+) -> Result<JsonValue> {
+    let base =
+        std::env::var("RUNSEAL_GITHUB_API_BASE").unwrap_or_else(|_| GITHUB_API_BASE.to_string());
+    let path = if path.starts_with('/') {
+        path.to_string()
+    } else {
+        format!("/{path}")
+    };
+    let url = format!("{base}{path}");
+    let client = reqwest::blocking::Client::builder()
+        .timeout(Duration::from_secs(30))
+        .build()?;
+    let method = method
+        .parse::<reqwest::Method>()
+        .with_context(|| format!("invalid HTTP method: {method}"))?;
+    let mut request = client
+        .request(method.clone(), &url)
+        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
+        .header("X-GitHub-Api-Version", GITHUB_API_VERSION)
+        .header(reqwest::header::USER_AGENT, "runseal");
+    if let Some(token) = token.filter(|value| !value.is_empty()) {
+        request = request.header(reqwest::header::AUTHORIZATION, format!("Bearer {token}"));
+    }
+    if let Some(body) = body {
+        request = request
+            .header(reqwest::header::CONTENT_TYPE, "application/json")
+            .json(&body);
+    }
+    let response = request
+        .send()
+        .with_context(|| format!("GitHub API {method} {path} unreachable"))?;
+    let status = response.status();
+    let raw = response
+        .text()
+        .with_context(|| format!("GitHub API {method} {path} returned unreadable body"))?;
+    if !status.is_success() {
+        bail!("GitHub API {method} {path} -> {}: {raw}", status.as_u16());
+    }
+    if raw.trim().is_empty() {
+        return Ok(JsonValue::Object(Default::default()));
+    }
+    serde_json::from_str(&raw)
+        .with_context(|| format!("GitHub API returned invalid JSON for {path}"))
+}
+
+pub fn read_body(args: &[String]) -> Result<String> {
+    let inline = optional_option(args, "--body");
+    let file = optional_option(args, "--body-file");
+    match (inline, file) {
+        (Some(_), Some(_)) => bail!("pass exactly one of --body or --body-file"),
+        (None, None) => bail!("pass exactly one of --body or --body-file"),
+        (Some(body), None) => Ok(body),
+        (None, Some(path)) => std::fs::read_to_string(&path)
+            .with_context(|| format!("failed to read body file: {path}")),
+    }
+}
+
+pub fn validate_body_max(args: &[String], body: &str, default_body_max: usize) -> Result<()> {
+    let body_max = body_max(args, default_body_max)?;
+    if body_max == 0 {
+        return Ok(());
+    }
+    let count = body.chars().count();
+    if count > body_max {
+        bail!("body length {count} exceeds --body-max={body_max}");
+    }
+    Ok(())
+}
+
+pub fn token(args: &[String]) -> Result<String> {
+    if let Some(token) = optional_option(args, "--token")
+        && !token.is_empty()
+    {
+        return Ok(token);
+    }
+    if let Some(path) = optional_option(args, "--token-file") {
+        let values = parse_env_file(Path::new(&path))?;
+        if let Some(token) = values.get("GITHUB_TOKEN").filter(|value| !value.is_empty()) {
+            return Ok(token.clone());
+        }
+        bail!("GITHUB_TOKEN not set in {path}");
+    }
+    if let Some(name) = optional_option(args, "--token-env") {
+        let token = std::env::var(&name)
+            .with_context(|| format!("environment variable not set: {name}"))?;
+        if token.is_empty() {
+            bail!("environment variable is empty: {name}");
+        }
+        return Ok(token);
+    }
+    if let Ok(token) = std::env::var("GITHUB_TOKEN")
+        && !token.is_empty()
+    {
+        return Ok(token);
+    }
+    bail!("missing GitHub token: pass --token, --token-file, --token-env, or set GITHUB_TOKEN")
+}
+
+pub fn optional_token(args: &[String]) -> Result<Option<String>> {
+    if let Some(token) = optional_option(args, "--token")
+        && !token.is_empty()
+    {
+        return Ok(Some(token));
+    }
+    if let Some(path) = optional_option(args, "--token-file") {
+        let values = parse_env_file(Path::new(&path))?;
+        if let Some(token) = values.get("GITHUB_TOKEN").filter(|value| !value.is_empty()) {
+            return Ok(Some(token.clone()));
+        }
+        bail!("GITHUB_TOKEN not set in {path}");
+    }
+    if let Some(name) = optional_option(args, "--token-env") {
+        let token = std::env::var(&name)
+            .with_context(|| format!("environment variable not set: {name}"))?;
+        if token.is_empty() {
+            bail!("environment variable is empty: {name}");
+        }
+        return Ok(Some(token));
+    }
+    Ok(std::env::var("GITHUB_TOKEN")
+        .ok()
+        .filter(|value| !value.is_empty()))
+}
+
+pub fn prefix_enabled(args: &[String]) -> Result<bool> {
+    optional_bool_option(args, "--prefix-enable").map(|value| value.unwrap_or(false))
+}
+
+pub fn current_repo_id() -> Result<String> {
+    let output = Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .output()
+        .with_context(|| "failed to execute command: git")?;
+    if !output.status.success() {
+        bail!(
+            "git remote get-url origin failed with status {}",
+            output.status.code().unwrap_or(1)
+        );
+    }
+    let url = String::from_utf8(output.stdout)
+        .with_context(|| "git remote get-url origin returned non-UTF-8 output")?;
+    parse_repo_id(url.trim())
+}
+
+pub fn current_github_repo_id() -> Result<String> {
+    let repo = current_repo_id()?;
+    if repo.contains('/') {
+        return Ok(repo);
+    }
+    bail!("cannot parse GitHub owner/repo from current repository")
+}
+
+pub fn current_branch() -> Result<String> {
+    let output = Command::new("git")
+        .args(["branch", "--show-current"])
+        .output()
+        .with_context(|| "failed to execute command: git")?;
+    if !output.status.success() {
+        bail!(
+            "git branch --show-current failed with status {}",
+            output.status.code().unwrap_or(1)
+        );
+    }
+    let branch = String::from_utf8(output.stdout)
+        .with_context(|| "git branch --show-current returned non-UTF-8 output")?;
+    let branch = branch.trim();
+    if branch.is_empty() {
+        bail!("git branch --show-current returned an empty branch name");
+    }
+    Ok(branch.to_string())
+}
+
+pub fn required_option(args: &[String], name: &str) -> Result<String> {
+    optional_option(args, name).ok_or_else(|| anyhow::anyhow!("{name} is required"))
+}
+
+pub fn core_repo_contains(repo: &str) -> bool {
+    CORE_REPOS
+        .iter()
+        .any(|value| value.eq_ignore_ascii_case(repo))
+}
+
+fn body_max(args: &[String], default: usize) -> Result<usize> {
+    let Some(value) = optional_option(args, "--body-max") else {
+        return Ok(default);
+    };
+    value
+        .parse::<usize>()
+        .with_context(|| format!("invalid --body-max: {value}"))
+}
+
+fn optional_bool_option(args: &[String], name: &str) -> Result<Option<bool>> {
+    let prefix = format!("{name}=");
+    let mut index = 0;
+    while index < args.len() {
+        let arg = &args[index];
+        if arg == name {
+            return Ok(Some(true));
+        }
+        if let Some(value) = arg.strip_prefix(&prefix) {
+            return Ok(Some(parse_bool(name, value)?));
+        }
+        if arg == name {
+            let Some(value) = args.get(index + 1) else {
+                return Ok(Some(true));
+            };
+            if !value.starts_with('-') {
+                return Ok(Some(parse_bool(name, value)?));
+            }
+            return Ok(Some(true));
+        }
+        index += 1;
+    }
+    Ok(None)
+}
+
+fn parse_bool(name: &str, value: &str) -> Result<bool> {
+    match value {
+        "true" => Ok(true),
+        "false" => Ok(false),
+        _ => bail!("{name} expects true or false"),
+    }
+}
+
+fn parse_repo_id(url: &str) -> Result<String> {
+    if let Ok(repo) = parse_hosted_repo_id(
+        url,
+        &[
+            "git@github.com:",
+            "ssh://git@github.com/",
+            "https://github.com/",
+            "http://github.com/",
+        ],
+    ) {
+        return Ok(repo);
+    }
+    if let Ok(repo) = parse_hosted_repo_id(
+        url,
+        &[
+            "git@gitee.com:",
+            "ssh://git@gitee.com/",
+            "https://gitee.com/",
+            "http://gitee.com/",
+        ],
+    ) {
+        return Ok(repo);
+    }
+    bail!("cannot parse owner/repo from origin url: {url}");
+}
+
+fn parse_hosted_repo_id(url: &str, prefixes: &[&str]) -> Result<String> {
+    let Some(after_host) = url
+        .strip_prefix(prefixes[0])
+        .or_else(|| url.strip_prefix(prefixes[1]))
+        .or_else(|| url.strip_prefix(prefixes[2]))
+        .or_else(|| url.strip_prefix(prefixes[3]))
+    else {
+        bail!("unmatched host");
+    };
+    let path = after_host.trim_end_matches(".git");
+    let mut parts = path.split('/');
+    let Some(owner) = parts.next().filter(|value| !value.is_empty()) else {
+        bail!("cannot parse owner/repo from origin url: {url}");
+    };
+    let Some(repo) = parts.next().filter(|value| !value.is_empty()) else {
+        bail!("cannot parse owner/repo from origin url: {url}");
+    };
+    if parts.next().is_some() {
+        bail!("cannot parse owner/repo from origin url: {url}");
+    }
+    Ok(format!("{owner}/{repo}"))
+}
+
+fn parse_env_file(path: &Path) -> Result<BTreeMap<String, String>> {
+    let text = std::fs::read_to_string(path)
+        .with_context(|| format!("failed to read token file: {}", path.display()))?;
+    let mut values = BTreeMap::new();
+    for line in text.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let Some((key, value)) = line.split_once('=') else {
+            bail!("invalid line in {}: {line}", path.display());
+        };
+        values.insert(
+            key.trim().to_string(),
+            value
+                .trim()
+                .trim_matches('"')
+                .trim_matches('\'')
+                .to_string(),
+        );
+    }
+    Ok(values)
+}
+
+fn optional_option(args: &[String], name: &str) -> Option<String> {
+    let prefix = format!("{name}=");
+    let mut index = 0;
+    while index < args.len() {
+        let arg = &args[index];
+        if arg == name {
+            return args.get(index + 1).cloned();
+        }
+        if let Some(value) = arg.strip_prefix(&prefix) {
+            return Some(value.to_string());
+        }
+        index += 1;
+    }
+    None
+}
diff --git a/app/src/core/tool/hash/mod.rs b/app/src/core/tool/hash/mod.rs
new file mode 100644
index 0000000..7831b09
--- /dev/null
+++ b/app/src/core/tool/hash/mod.rs
@@ -0,0 +1,73 @@
+use std::{
+    fs,
+    io::Read,
+    path::{Path, PathBuf},
+};
+
+use anyhow::{Context, Result, bail};
+use sha2::{Digest, Sha256};
+
+pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
+    match command {
+        "tree" => tree(args),
+        _ => bail!("unknown tool command: hash {command}"),
+    }
+}
+
+fn tree(args: &[String]) -> Result<Option<String>> {
+    if args.is_empty() {
+        bail!("usage: runseal @tool hash tree <path>...");
+    }
+    let mut entries = Vec::new();
+    for input in args {
+        let path = Path::new(input);
+        collect(path, PathBuf::from(input), &mut entries)?;
+    }
+    entries.sort_by(|left, right| left.0.cmp(&right.0));
+
+    let mut hasher = Sha256::new();
+    for (label, file) in entries {
+        hasher.update(label.as_bytes());
+        hasher.update([0]);
+        let mut handle = fs::File::open(&file)
+            .with_context(|| format!("failed to open file: {}", file.display()))?;
+        let mut buffer = Vec::new();
+        handle
+            .read_to_end(&mut buffer)
+            .with_context(|| format!("failed to read file: {}", file.display()))?;
+        hasher.update(&buffer);
+        hasher.update([0]);
+    }
+
+    Ok(Some(format!("{:x}", hasher.finalize())))
+}
+
+fn collect(path: &Path, label: PathBuf, entries: &mut Vec<(String, PathBuf)>) -> Result<()> {
+    let metadata =
+        fs::metadata(path).with_context(|| format!("path not found: {}", path.display()))?;
+    if metadata.is_file() {
+        entries.push((normalize(&label), path.to_path_buf()));
+        return Ok(());
+    }
+    if metadata.is_dir() {
+        for entry in fs::read_dir(path)
+            .with_context(|| format!("failed to read directory: {}", path.display()))?
+        {
+            let entry =
+                entry.with_context(|| format!("failed to read entry: {}", path.display()))?;
+            let name = entry.file_name();
+            let child_path = entry.path();
+            let child_label = label.join(&name);
+            collect(&child_path, child_label, entries)?;
+        }
+        return Ok(());
+    }
+    bail!("unsupported path for hash tree: {}", path.display())
+}
+
+fn normalize(path: &Path) -> String {
+    path.components()
+        .map(|component| component.as_os_str().to_string_lossy())
+        .collect::<Vec<_>>()
+        .join("/")
+}
diff --git a/app/src/core/tool/help/basic.rs b/app/src/core/tool/help/basic.rs
index 294a615..59bfd7f 100644
--- a/app/src/core/tool/help/basic.rs
+++ b/app/src/core/tool/help/basic.rs
@@ -89,7 +89,13 @@ pub const PROCESS: Entry = Entry {
     about: None,
     sections: &[Section {
         title: "Process helpers",
-        items: &[("exists <name>", "print true when command exists on PATH")],
+        items: &[
+            ("exists <name>", "print true when command exists on PATH"),
+            (
+                "write <stdout|stderr> <path> [--append] -- <command> [args...]",
+                "run one command and write one stream to a file",
+            ),
+        ],
     }],
     examples: &[],
 };
@@ -102,6 +108,22 @@ pub const PROCESS_EXISTS: Entry = Entry {
     examples: &[],
 };
 
+pub const PROCESS_WRITE: Entry = Entry {
+    key: "process.write",
+    usage: "runseal @tool process write <stdout|stderr> <path> [--append] -- <command> [args...]",
+    about: Some(
+        "Run one command, write one selected stream to a file, and pass the other stream through.",
+    ),
+    sections: &[Section {
+        title: "Flags",
+        items: &[("--append", "append instead of overwriting the target file")],
+    }],
+    examples: &[
+        "runseal @tool process write stdout openapi.json -- cargo run -- export-openapi",
+        "runseal @tool process write stderr build.log --append -- cargo build",
+    ],
+};
+
 pub const ARCHIVE: Entry = Entry {
     key: "archive",
     usage: "runseal @tool archive <scope> <command> [args]",
@@ -248,6 +270,7 @@ pub const GITEE: Entry = Entry {
                 "repo parse-origin <url>",
                 "parse owner/repo from origin URL",
             ),
+            ("pr find", "find one pull request by branch filters"),
             ("pr create", "create a pull request"),
             ("pr pass-gates", "best-effort pass PR gates"),
             ("pr merge", "merge a pull request"),
@@ -285,6 +308,7 @@ pub const GITEE_PR: Entry = Entry {
     sections: &[Section {
         title: "Gitee PR helpers",
         items: &[
+            ("find", "find one Gitee pull request"),
             ("create", "create a Gitee pull request"),
             ("pass-gates", "best-effort pass PR gates"),
             ("merge", "merge a Gitee pull request"),
@@ -293,9 +317,43 @@ pub const GITEE_PR: Entry = Entry {
     examples: &[],
 };
 
+pub const GITEE_PR_FIND: Entry = Entry {
+    key: "gitee.pr.find",
+    usage: "runseal @tool gitee pr find --owner <name> --repo <name> --head <branch> [--base <branch>] [--state <open|merged|closed|all>] [--token <text>|--token-file <path>|--token-env <name>]",
+    about: Some(
+        "Find one Gitee pull request by branch filters. Prints the PR JSON object or `null` when no match exists.",
+    ),
+    sections: &[Section {
+        title: "Flags",
+        items: &[
+            ("--owner <name>", "Gitee repository owner"),
+            ("--repo <name>", "Gitee repository name"),
+            ("--head <branch>", "source branch to match"),
+            ("--base <branch>", "optional target branch filter"),
+            (
+                "--state <open|merged|closed|all>",
+                "PR state filter; default `open`",
+            ),
+            ("--token <text>", "explicit Gitee token"),
+            (
+                "--token-file <path>",
+                "env-style file containing `GITEE_TOKEN`",
+            ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITEE_TOKEN`",
+            ),
+        ],
+    }],
+    examples: &[
+        "runseal @tool gitee pr find --owner perishme --repo perish.top --head auto/demo",
+        "runseal @tool gitee pr find --owner perishme --repo perish.top --head feat/resume --base main --state open",
+    ],
+};
+
 pub const GITEE_PR_CREATE: Entry = Entry {
     key: "gitee.pr.create",
-    usage: "runseal @tool gitee pr create --owner <name> --repo <name> --base <branch> --head <branch> --title <text> --body <text> [--token <text>|--token-file <path>]",
+    usage: "runseal @tool gitee pr create --owner <name> --repo <name> --base <branch> --head <branch> --title <text> --body <text> [--token <text>|--token-file <path>|--token-env <name>]",
     about: Some("Create a Gitee pull request and print the API response JSON."),
     sections: &[Section {
         title: "Flags",
@@ -311,6 +369,10 @@ pub const GITEE_PR_CREATE: Entry = Entry {
                 "--token-file <path>",
                 "env-style file containing `GITEE_TOKEN`",
             ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITEE_TOKEN`",
+            ),
         ],
     }],
     examples: &[
@@ -320,7 +382,7 @@ pub const GITEE_PR_CREATE: Entry = Entry {
 
 pub const GITEE_PR_PASS_GATES: Entry = Entry {
     key: "gitee.pr.pass-gates",
-    usage: "runseal @tool gitee pr pass-gates --owner <name> --repo <name> --number <n> [--token <text>|--token-file <path>]",
+    usage: "runseal @tool gitee pr pass-gates --owner <name> --repo <name> --number <n> [--token <text>|--token-file <path>|--token-env <name>]",
     about: Some("Best-effort pass available Gitee PR gates and print the result JSON."),
     sections: &[Section {
         title: "Flags",
@@ -333,6 +395,10 @@ pub const GITEE_PR_PASS_GATES: Entry = Entry {
                 "--token-file <path>",
                 "env-style file containing `GITEE_TOKEN`",
             ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITEE_TOKEN`",
+            ),
         ],
     }],
     examples: &[
@@ -342,7 +408,7 @@ pub const GITEE_PR_PASS_GATES: Entry = Entry {
 
 pub const GITEE_PR_MERGE: Entry = Entry {
     key: "gitee.pr.merge",
-    usage: "runseal @tool gitee pr merge --owner <name> --repo <name> --number <n> [--method <merge|rebase|squash>] [--token <text>|--token-file <path>]",
+    usage: "runseal @tool gitee pr merge --owner <name> --repo <name> --number <n> [--method <merge|rebase|squash>] [--token <text>|--token-file <path>|--token-env <name>]",
     about: Some("Merge a Gitee pull request and print the API response JSON."),
     sections: &[Section {
         title: "Flags",
@@ -359,47 +425,13 @@ pub const GITEE_PR_MERGE: Entry = Entry {
                 "--token-file <path>",
                 "env-style file containing `GITEE_TOKEN`",
             ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITEE_TOKEN`",
+            ),
         ],
     }],
     examples: &[
         "runseal @tool gitee pr merge --owner perishme --repo perish.top --number 123 --method squash",
     ],
 };
-
-pub const GITHUB: Entry = Entry {
-    key: "github",
-    usage: "runseal @tool github <scope> <command> [args]",
-    about: None,
-    sections: &[Section {
-        title: "GitHub helpers",
-        items: &[(
-            "pr checks probe <number>",
-            "print true when PR checks are reported",
-        )],
-    }],
-    examples: &[],
-};
-
-pub const GITHUB_PR: Entry = Entry {
-    key: "github.pr",
-    usage: "runseal @tool github pr checks probe <number>",
-    about: None,
-    sections: &[],
-    examples: &[],
-};
-
-pub const GITHUB_PR_CHECKS: Entry = Entry {
-    key: "github.pr.checks",
-    usage: "runseal @tool github pr checks probe <number>",
-    about: None,
-    sections: &[],
-    examples: &[],
-};
-
-pub const GITHUB_PR_CHECKS_PROBE: Entry = Entry {
-    key: "github.pr.checks.probe",
-    usage: "runseal @tool github pr checks probe <number>",
-    about: None,
-    sections: &[],
-    examples: &[],
-};
diff --git a/app/src/core/tool/help/github.rs b/app/src/core/tool/help/github.rs
new file mode 100644
index 0000000..c85610d
--- /dev/null
+++ b/app/src/core/tool/help/github.rs
@@ -0,0 +1,175 @@
+use super::{Entry, Section};
+
+pub const GITHUB: Entry = Entry {
+    key: "github",
+    usage: "runseal @tool github <scope> <command> [args]",
+    about: Some("GitHub helpers for collaboration rules that need more than plain gh ergonomics."),
+    sections: &[Section {
+        title: "GitHub helpers",
+        items: &[
+            (
+                "issue create",
+                "create one issue with optional body shaping",
+            ),
+            (
+                "issue comment create",
+                "create one issue-style comment; also applies to top-level PR comments",
+            ),
+            (
+                "issue body update",
+                "update one issue-style body; also applies to top-level PR bodies",
+            ),
+        ],
+    }],
+    examples: &[],
+};
+
+pub const GITHUB_ISSUE: Entry = Entry {
+    key: "github.issue",
+    usage: "runseal @tool github issue <scope> <command> [args]",
+    about: Some(
+        "GitHub issue-style write helpers. GitHub PR top-level bodies and timeline comments also use this issue model.",
+    ),
+    sections: &[Section {
+        title: "GitHub issue helpers",
+        items: &[
+            ("create", "create one issue"),
+            ("comment create", "create one issue-style comment"),
+            ("body update", "update one issue-style body"),
+        ],
+    }],
+    examples: &[],
+};
+
+pub const GITHUB_ISSUE_CREATE: Entry = Entry {
+    key: "github.issue.create",
+    usage: "runseal @tool github issue create --repo <owner/name> --title <text> [--body <text>|--body-file <path>] [--body-max <n>] [--prefix-enable=<true|false>] [--token <text>|--token-file <path>|--token-env <name>]",
+    about: Some(
+        "Create one GitHub issue and print the API response JSON. Body is optional. Default `--body-max` is `0`, which means unlimited.",
+    ),
+    sections: &[Section {
+        title: "Flags",
+        items: &[
+            ("--repo <owner/name>", "target GitHub repository"),
+            ("--title <text>", "issue title"),
+            ("--body <text>", "inline body text"),
+            ("--body-file <path>", "read body text from one file"),
+            (
+                "--body-max <n>",
+                "maximum user-body length; `0` disables the limit; default `0`",
+            ),
+            (
+                "--prefix-enable=<true|false>",
+                "prepend requested-by metadata for matching cross-repo writes",
+            ),
+            ("--token <text>", "explicit GitHub token"),
+            (
+                "--token-file <path>",
+                "env-style file containing `GITHUB_TOKEN`",
+            ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITHUB_TOKEN`",
+            ),
+        ],
+    }],
+    examples: &[
+        "runseal @tool github issue create --repo PerishCode/runseal --title demo --body-file body.md --prefix-enable=true",
+    ],
+};
+
+pub const GITHUB_ISSUE_COMMENT: Entry = Entry {
+    key: "github.issue.comment",
+    usage: "runseal @tool github issue comment create [args]",
+    about: None,
+    sections: &[Section {
+        title: "GitHub issue comment helpers",
+        items: &[("create", "create one issue-style comment")],
+    }],
+    examples: &[],
+};
+
+pub const GITHUB_ISSUE_COMMENT_CREATE: Entry = Entry {
+    key: "github.issue.comment.create",
+    usage: "runseal @tool github issue comment create --repo <owner/name> --number <n> (--body <text>|--body-file <path>) [--body-max <n>] [--prefix-enable=<true|false>] [--token <text>|--token-file <path>|--token-env <name>]",
+    about: Some(
+        "Create one GitHub issue-style comment and print the API response JSON. Default `--body-max` is `100`; over-limit bodies fail fast.",
+    ),
+    sections: &[Section {
+        title: "Flags",
+        items: &[
+            ("--repo <owner/name>", "target GitHub repository"),
+            ("--number <n>", "issue or pull request number"),
+            ("--body <text>", "inline comment body"),
+            ("--body-file <path>", "read comment body from one file"),
+            (
+                "--body-max <n>",
+                "maximum user-body length; `0` disables the limit; default `100`",
+            ),
+            (
+                "--prefix-enable=<true|false>",
+                "prepend requested-by metadata for matching cross-repo writes",
+            ),
+            ("--token <text>", "explicit GitHub token"),
+            (
+                "--token-file <path>",
+                "env-style file containing `GITHUB_TOKEN`",
+            ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITHUB_TOKEN`",
+            ),
+        ],
+    }],
+    examples: &[
+        "runseal @tool github issue comment create --repo PerishCode/runseal --number 46 --body-file body.md --prefix-enable=true",
+    ],
+};
+
+pub const GITHUB_ISSUE_BODY: Entry = Entry {
+    key: "github.issue.body",
+    usage: "runseal @tool github issue body update [args]",
+    about: None,
+    sections: &[Section {
+        title: "GitHub issue body helpers",
+        items: &[("update", "update one issue-style body")],
+    }],
+    examples: &[],
+};
+
+pub const GITHUB_ISSUE_BODY_UPDATE: Entry = Entry {
+    key: "github.issue.body.update",
+    usage: "runseal @tool github issue body update --repo <owner/name> --number <n> (--body <text>|--body-file <path>) [--body-max <n>] [--prefix-enable=<true|false>] [--token <text>|--token-file <path>|--token-env <name>]",
+    about: Some(
+        "Update one GitHub issue-style body and print the API response JSON. Default `--body-max` is `0`, which means unlimited.",
+    ),
+    sections: &[Section {
+        title: "Flags",
+        items: &[
+            ("--repo <owner/name>", "target GitHub repository"),
+            ("--number <n>", "issue or pull request number"),
+            ("--body <text>", "inline body text"),
+            ("--body-file <path>", "read body text from one file"),
+            (
+                "--body-max <n>",
+                "maximum user-body length; `0` disables the limit; default `0`",
+            ),
+            (
+                "--prefix-enable=<true|false>",
+                "prepend requested-by metadata for matching cross-repo writes",
+            ),
+            ("--token <text>", "explicit GitHub token"),
+            (
+                "--token-file <path>",
+                "env-style file containing `GITHUB_TOKEN`",
+            ),
+            (
+                "--token-env <name>",
+                "read the token from one named environment variable; default fallback is `GITHUB_TOKEN`",
+            ),
+        ],
+    }],
+    examples: &[
+        "runseal @tool github issue body update --repo PerishCode/runseal --number 46 --body-file body.md --prefix-enable=true",
+    ],
+};
diff --git a/app/src/core/tool/help/hash_version.rs b/app/src/core/tool/help/hash_version.rs
new file mode 100644
index 0000000..ecac6c5
--- /dev/null
+++ b/app/src/core/tool/help/hash_version.rs
@@ -0,0 +1,59 @@
+use super::{Entry, Section};
+
+pub const HASH: Entry = Entry {
+    key: "hash",
+    usage: "runseal @tool hash <command> [args]",
+    about: None,
+    sections: &[Section {
+        title: "Hash helpers",
+        items: &[(
+            "tree <path>...",
+            "hash one or more file trees deterministically",
+        )],
+    }],
+    examples: &[],
+};
+
+pub const HASH_TREE: Entry = Entry {
+    key: "hash.tree",
+    usage: "runseal @tool hash tree <path>...",
+    about: Some("Hash one or more file trees using stable path and content ordering."),
+    sections: &[],
+    examples: &["runseal @tool hash tree app/tests .runseal/wrappers"],
+};
+
+pub const VERSION: Entry = Entry {
+    key: "version",
+    usage: "runseal @tool version <command> [args]",
+    about: None,
+    sections: &[Section {
+        title: "Version helpers",
+        items: &[
+            (
+                "part <version> <major|minor|patch>",
+                "print one stable semantic version part",
+            ),
+            (
+                "compare <left> <right>",
+                "compare two stable semantic versions",
+            ),
+        ],
+    }],
+    examples: &[],
+};
+
+pub const VERSION_PART: Entry = Entry {
+    key: "version.part",
+    usage: "runseal @tool version part <version> <major|minor|patch>",
+    about: Some("Print one numeric part from a stable semantic version, with optional `v` prefix."),
+    sections: &[],
+    examples: &["runseal @tool version part v0.7.0 minor"],
+};
+
+pub const VERSION_COMPARE: Entry = Entry {
+    key: "version.compare",
+    usage: "runseal @tool version compare <left> <right>",
+    about: Some("Compare two stable semantic versions and print `lt`, `eq`, or `gt`."),
+    sections: &[],
+    examples: &["runseal @tool version compare 0.6.1 0.6.0"],
+};
diff --git a/app/src/core/tool/help/json.rs b/app/src/core/tool/help/json.rs
index f0b71b4..f371918 100644
--- a/app/src/core/tool/help/json.rs
+++ b/app/src/core/tool/help/json.rs
@@ -8,6 +8,7 @@ pub const JSON: Entry = Entry {
         title: "JSON helpers",
         items: &[
             ("get <json> <path>", "print one JSON value"),
+            ("has <json> <path>", "print true when the JSON path exists"),
             ("empty <json>", "print true when JSON length is zero"),
             ("len <json>", "print JSON array/object/string length"),
             ("pretty <mode> ...", "print formatted JSON"),
@@ -38,6 +39,22 @@ pub const JSON_GET: Entry = Entry {
     examples: &["runseal @tool json get '[{\"databaseId\":123}]' '.[0].databaseId'"],
 };
 
+pub const JSON_HAS: Entry = Entry {
+    key: "json.has",
+    usage: "runseal @tool json has <json> <path>",
+    about: Some("Print `true` when the JSON path exists, otherwise `false`."),
+    sections: &[Section {
+        title: "Arguments",
+        items: &[
+            ("<json>", "input JSON text"),
+            ("<path>", "path expression such as `.guard.version.hash`"),
+        ],
+    }],
+    examples: &[
+        "runseal @tool json has '{\"guard\":{\"version\":{\"hash\":\"x\"}}}' .guard.version.hash",
+    ],
+};
+
 pub const JSON_EMPTY: Entry = Entry {
     key: "json.empty",
     usage: "runseal @tool json empty <json>",
diff --git a/app/src/core/tool/help/mod.rs b/app/src/core/tool/help/mod.rs
index 81c79f5..860de87 100644
--- a/app/src/core/tool/help/mod.rs
+++ b/app/src/core/tool/help/mod.rs
@@ -1,5 +1,7 @@
 mod basic;
 mod cloudflare;
+mod github;
+mod hash_version;
 mod json;
 mod ssh;
 
@@ -21,6 +23,7 @@ pub struct Section {
 const ENTRIES: &[Entry] = &[
     json::JSON,
     json::JSON_GET,
+    json::JSON_HAS,
     json::JSON_EMPTY,
     json::JSON_LEN,
     json::JSON_PRETTY,
@@ -29,6 +32,8 @@ const ENTRIES: &[Entry] = &[
     json::JSON_PRETTY_FILE,
     json::JSON_FIND,
     json::JSON_FILTER,
+    hash_version::HASH,
+    hash_version::HASH_TREE,
     basic::STRING,
     basic::STRING_TRIM,
     basic::STRING_JOIN,
@@ -39,6 +44,7 @@ const ENTRIES: &[Entry] = &[
     basic::INT_ADD,
     basic::PROCESS,
     basic::PROCESS_EXISTS,
+    basic::PROCESS_WRITE,
     basic::ARCHIVE,
     basic::ARCHIVE_LOCAL,
     basic::ARCHIVE_LOCAL_EXPORT,
@@ -49,13 +55,20 @@ const ENTRIES: &[Entry] = &[
     basic::GITEE_REPO,
     basic::GITEE_REPO_PARSE_ORIGIN,
     basic::GITEE_PR,
+    basic::GITEE_PR_FIND,
     basic::GITEE_PR_CREATE,
     basic::GITEE_PR_PASS_GATES,
     basic::GITEE_PR_MERGE,
-    basic::GITHUB,
-    basic::GITHUB_PR,
-    basic::GITHUB_PR_CHECKS,
-    basic::GITHUB_PR_CHECKS_PROBE,
+    hash_version::VERSION,
+    hash_version::VERSION_PART,
+    hash_version::VERSION_COMPARE,
+    github::GITHUB,
+    github::GITHUB_ISSUE,
+    github::GITHUB_ISSUE_CREATE,
+    github::GITHUB_ISSUE_COMMENT,
+    github::GITHUB_ISSUE_COMMENT_CREATE,
+    github::GITHUB_ISSUE_BODY,
+    github::GITHUB_ISSUE_BODY_UPDATE,
     ssh::SSH,
     ssh::SSH_CONFIG,
     ssh::SSH_CONFIG_HOST,
@@ -97,12 +110,14 @@ Run an atomic runseal tool command.
 
 Tools:
   json ...                               JSON helpers
+  hash ...                               hash helpers
   string ...                             string helpers
   regex ...                              regex helpers
   int ...                                integer helpers
   process ...                            process helpers
   archive ...                            archive helpers
   fs ...                                 filesystem helpers
+  version ...                            version helpers
   gitee ...                              gitee helpers
   ssh ...                                ssh helpers
   github ...                             github helpers
diff --git a/app/src/core/tool/json.rs b/app/src/core/tool/json.rs
index 05836b7..1d23b71 100644
--- a/app/src/core/tool/json.rs
+++ b/app/src/core/tool/json.rs
@@ -6,6 +6,7 @@ use serde_json::Value as JsonValue;
 pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
     match command {
         "get" => get(args),
+        "has" => has(args),
         "empty" => empty(args),
         "len" => len(args),
         "pretty" => pretty(args),
@@ -31,6 +32,14 @@ fn get(args: &[String]) -> Result<Option<String>> {
     Ok(output)
 }
 
+fn has(args: &[String]) -> Result<Option<String>> {
+    let [json, path] = args else {
+        bail!("usage: runseal @tool json has <json> <path>");
+    };
+    let value: JsonValue = serde_json::from_str(json).context("invalid JSON input")?;
+    Ok(Some(path_exists(&value, path).to_string()))
+}
+
 fn empty(args: &[String]) -> Result<Option<String>> {
     let [json] = args else {
         bail!("usage: runseal @tool json empty <json>");
@@ -167,6 +176,18 @@ fn value_is_empty(value: &JsonValue) -> bool {
 }
 
 fn select_path<'a>(value: &'a JsonValue, path: &str) -> Result<&'a JsonValue> {
+    select_path_impl(value, path, true)
+}
+
+fn path_exists(value: &JsonValue, path: &str) -> bool {
+    select_path_impl(value, path, false).is_ok()
+}
+
+fn select_path_impl<'a>(
+    value: &'a JsonValue,
+    path: &str,
+    error_on_missing: bool,
+) -> Result<&'a JsonValue> {
     let mut input = path.strip_prefix('.').unwrap_or(path);
     if input.is_empty() {
         bail!("json path cannot be empty");
@@ -180,18 +201,26 @@ fn select_path<'a>(value: &'a JsonValue, path: &str) -> Result<&'a JsonValue> {
             let index = index
                 .parse::<usize>()
                 .with_context(|| format!("invalid json path index: {index}"))?;
-            current = current
-                .get(index)
-                .with_context(|| format!("json path not found: {path}"))?;
+            current = current.get(index).ok_or_else(|| {
+                if error_on_missing {
+                    anyhow::anyhow!("json path not found: {path}")
+                } else {
+                    anyhow::anyhow!("missing")
+                }
+            })?;
             input = rest.strip_prefix('.').unwrap_or(rest);
             continue;
         }
         let end = input.find(['.', '[']).unwrap_or(input.len());
         let field = &input[..end];
         validate_field(field)?;
-        current = current
-            .get(field)
-            .with_context(|| format!("json path not found: {path}"))?;
+        current = current.get(field).ok_or_else(|| {
+            if error_on_missing {
+                anyhow::anyhow!("json path not found: {path}")
+            } else {
+                anyhow::anyhow!("missing")
+            }
+        })?;
         input = input[end..].strip_prefix('.').unwrap_or(&input[end..]);
     }
     Ok(current)
diff --git a/app/src/core/tool/mod.rs b/app/src/core/tool/mod.rs
index 3025af3..231c95f 100644
--- a/app/src/core/tool/mod.rs
+++ b/app/src/core/tool/mod.rs
@@ -5,6 +5,7 @@ mod cloudflare;
 mod fs;
 mod gitee;
 mod github;
+mod hash;
 mod help;
 mod int;
 mod json;
@@ -12,6 +13,7 @@ mod process;
 mod regex;
 mod ssh;
 mod string;
+mod version;
 
 pub fn help() -> &'static str {
     help::top()
@@ -41,7 +43,9 @@ pub fn eval(args: &[String]) -> Result<Option<String>> {
         [namespace, command, rest @ ..] if namespace == "archive" => archive::eval(command, rest),
         [namespace, command, rest @ ..] if namespace == "fs" => fs::eval(command, rest),
         [namespace, command, rest @ ..] if namespace == "gitee" => gitee::eval(command, rest),
+        [namespace, command, rest @ ..] if namespace == "hash" => hash::eval(command, rest),
         [namespace, command, rest @ ..] if namespace == "ssh" => ssh::eval(command, rest),
+        [namespace, command, rest @ ..] if namespace == "version" => version::eval(command, rest),
         [namespace, command, rest @ ..] if namespace == "github" => github::eval(command, rest),
         [namespace, command, rest @ ..] if namespace == "cloudflare" => {
             cloudflare::eval(command, rest)
diff --git a/app/src/core/tool/process.rs b/app/src/core/tool/process.rs
index a9d25bc..a973545 100644
--- a/app/src/core/tool/process.rs
+++ b/app/src/core/tool/process.rs
@@ -1,8 +1,12 @@
-use anyhow::{Result, bail};
+use std::path::Path;
+use std::process::Command;
+
+use anyhow::{Context, Result, bail};
 
 pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
     match command {
         "exists" => exists(args),
+        "write" => write(args),
         _ => bail!("unknown tool command: process {command}"),
     }
 }
@@ -14,6 +18,95 @@ fn exists(args: &[String]) -> Result<Option<String>> {
     Ok(Some(command_exists(name).to_string()))
 }
 
+fn write(args: &[String]) -> Result<Option<String>> {
+    let [stream, path, rest @ ..] = args else {
+        bail!(
+            "usage: runseal @tool process write <stdout|stderr> <path> [--append] -- <command> [args...]"
+        );
+    };
+    let stream = parse_stream(stream)?;
+    let mut append = false;
+    let mut index = 0;
+    while index < rest.len() {
+        match rest[index].as_str() {
+            "--append" => {
+                append = true;
+                index += 1;
+            }
+            "--" => {
+                index += 1;
+                break;
+            }
+            other => bail!("unknown process write argument: {other}"),
+        }
+    }
+    let command_argv = &rest[index..];
+    let Some((program, command_args)) = command_argv.split_first() else {
+        bail!("process write requires one command after `--`");
+    };
+    let output = Command::new(program)
+        .args(command_args)
+        .output()
+        .with_context(|| format!("failed to execute command: {program}"))?;
+    let captured = match stream {
+        Stream::Stdout => &output.stdout,
+        Stream::Stderr => &output.stderr,
+    };
+    let passthrough = match stream {
+        Stream::Stdout => &output.stderr,
+        Stream::Stderr => &output.stdout,
+    };
+    if let Some(parent) = Path::new(path).parent()
+        && !parent.as_os_str().is_empty()
+    {
+        std::fs::create_dir_all(parent)
+            .with_context(|| format!("failed to create parent directory: {}", parent.display()))?;
+    }
+    if append {
+        use std::io::Write;
+        let mut file = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(path)
+            .with_context(|| format!("failed to append file: {path}"))?;
+        file.write_all(captured)
+            .with_context(|| format!("failed to append file: {path}"))?;
+    } else {
+        std::fs::write(path, captured).with_context(|| format!("failed to write file: {path}"))?;
+    }
+    match stream {
+        Stream::Stdout => {
+            use std::io::Write;
+            std::io::stderr()
+                .write_all(passthrough)
+                .context("failed to write stderr")?;
+        }
+        Stream::Stderr => {
+            use std::io::Write;
+            std::io::stdout()
+                .write_all(passthrough)
+                .context("failed to write stdout")?;
+        }
+    }
+    if output.status.success() {
+        return Ok(None);
+    }
+    std::process::exit(output.status.code().unwrap_or(1));
+}
+
+enum Stream {
+    Stdout,
+    Stderr,
+}
+
+fn parse_stream(value: &str) -> Result<Stream> {
+    match value {
+        "stdout" => Ok(Stream::Stdout),
+        "stderr" => Ok(Stream::Stderr),
+        _ => bail!("process write stream must be stdout or stderr"),
+    }
+}
+
 fn command_exists(name: &str) -> bool {
     let Some(path) = std::env::var_os("PATH") else {
         return false;
diff --git a/app/src/core/tool/version/mod.rs b/app/src/core/tool/version/mod.rs
new file mode 100644
index 0000000..e84a5db
--- /dev/null
+++ b/app/src/core/tool/version/mod.rs
@@ -0,0 +1,60 @@
+use anyhow::{Result, bail};
+
+pub fn eval(command: &str, args: &[String]) -> Result<Option<String>> {
+    match command {
+        "part" => part(args),
+        "compare" => compare(args),
+        _ => bail!("unknown tool command: version {command}"),
+    }
+}
+
+fn part(args: &[String]) -> Result<Option<String>> {
+    let [version, name] = args else {
+        bail!("usage: runseal @tool version part <version> <major|minor|patch>");
+    };
+    let parsed = parse(version)?;
+    let output = match name.as_str() {
+        "major" => parsed.0.to_string(),
+        "minor" => parsed.1.to_string(),
+        "patch" => parsed.2.to_string(),
+        _ => bail!("usage: runseal @tool version part <version> <major|minor|patch>"),
+    };
+    Ok(Some(output))
+}
+
+fn compare(args: &[String]) -> Result<Option<String>> {
+    let [left, right] = args else {
+        bail!("usage: runseal @tool version compare <left> <right>");
+    };
+    let left = parse(left)?;
+    let right = parse(right)?;
+    let output = if left < right {
+        "lt"
+    } else if left > right {
+        "gt"
+    } else {
+        "eq"
+    };
+    Ok(Some(output.to_string()))
+}
+
+fn parse(version: &str) -> Result<(u64, u64, u64)> {
+    let value = version.strip_prefix('v').unwrap_or(version);
+    let mut parts = value.split('.');
+    let major = parse_part(parts.next(), version, "major")?;
+    let minor = parse_part(parts.next(), version, "minor")?;
+    let patch = parse_part(parts.next(), version, "patch")?;
+    if parts.next().is_some() {
+        bail!("expected stable semantic version, got {version}");
+    }
+    Ok((major, minor, patch))
+}
+
+fn parse_part(value: Option<&str>, version: &str, name: &str) -> Result<u64> {
+    let Some(value) = value else {
+        bail!("expected stable semantic version, got {version}");
+    };
+    value
+        .parse::<u64>()
+        .map_err(|_| anyhow::anyhow!("invalid {name} version part in {version}"))
+}
diff --git a/app/src/core/transpile/ast.rs b/app/src/core/transpile/ast.rs
index 227d448..d883232 100644
--- a/app/src/core/transpile/ast.rs
+++ b/app/src/core/transpile/ast.rs
@@ -18,6 +18,12 @@ pub enum Statement {
         name: String,
         value: Value,
     },
+    ExecWrite {
+        stream: OutputStream,
+        path: Value,
+        append: bool,
+        argv: Vec<Value>,
+    },
     ExecChecked {
         argv: Vec<Value>,
     },
@@ -30,11 +36,17 @@ pub enum Statement {
     },
     ArgvParse {
         specs: Vec<ArgvSpec>,
+        positional: Option<ArgvPositional>,
     },
     CaptureChecked {
         name: String,
         argv: Vec<Value>,
     },
+    CaptureFunction {
+        name: String,
+        function: String,
+        argv: Vec<Value>,
+    },
     If {
         predicate: Predicate,
         then_body: Vec<Statement>,
@@ -83,6 +95,13 @@ pub struct ArgvSpec {
     pub default: Option<String>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ArgvPositional {
+    pub name: String,
+    pub default: String,
+    pub extra_error: String,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct EnvAssign {
     pub name: String,
@@ -99,13 +118,33 @@ pub enum ArgvKind {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(tag = "type", rename_all = "snake_case")]
 pub enum Value {
-    Literal { text: String },
+    Literal {
+        text: String,
+    },
     Argc,
-    Var { name: String },
     Args,
+    Expand {
+        source: ValueSource,
+        op: ExpansionOp,
+    },
+    Concat {
+        parts: Vec<Value>,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ValueSource {
+    Var { name: String },
     Env { name: String },
-    EnvDefault { name: String, default: String },
-    Concat { parts: Vec<Value> },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ExpansionOp {
+    Plain,
+    DefaultIfUnsetOrEmpty { fallback: String },
+    RequireNonEmpty { message: String },
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -125,4 +164,11 @@ pub enum Predicate {
     FileExists { path: Value },
     DirExists { path: Value },
 }
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum OutputStream {
+    Stdout,
+    Stderr,
+}
 use serde::{Deserialize, Serialize};
diff --git a/app/src/core/transpile/emit/mod.rs b/app/src/core/transpile/emit/mod.rs
index 1c94bd6..a47950b 100644
--- a/app/src/core/transpile/emit/mod.rs
+++ b/app/src/core/transpile/emit/mod.rs
@@ -1,7 +1,8 @@
-use super::ast::{ArgvKind, ArgvSpec, Item, Program, Statement};
+use super::ast::{ArgvKind, ArgvPositional, ArgvSpec, Item, OutputStream, Program, Statement};
 use super::guards::{bash_required_tools, emit_bash_guards};
 
 mod powershell;
+mod powershell_support;
 mod support;
 
 pub(crate) use powershell::emit_powershell;
@@ -42,6 +43,25 @@ fn emit_seal_statement(out: &mut String, statement: &Statement, indent: usize) {
             out.push_str(&join_values(argv, seal_value));
             out.push('\n');
         }
+        Statement::ExecWrite {
+            stream,
+            path,
+            append,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str(&join_values(argv, seal_value));
+            out.push(' ');
+            out.push_str(match (stream, append) {
+                (OutputStream::Stdout, false) => ">",
+                (OutputStream::Stdout, true) => ">>",
+                (OutputStream::Stderr, false) => "2>",
+                (OutputStream::Stderr, true) => "2>>",
+            });
+            out.push(' ');
+            out.push_str(&seal_value(path));
+            out.push('\n');
+        }
         Statement::EnvExecChecked { env, argv } => {
             out.push_str(&pad);
             for item in env {
@@ -62,8 +82,8 @@ fn emit_seal_statement(out: &mut String, statement: &Statement, indent: usize) {
             }
             out.push('\n');
         }
-        Statement::ArgvParse { specs } => {
-            emit_seal_argv_parse(out, specs, indent);
+        Statement::ArgvParse { specs, positional } => {
+            emit_seal_argv_parse(out, specs, positional.as_ref(), indent);
         }
         Statement::CaptureChecked { name, argv } => {
             out.push_str(&pad);
@@ -72,6 +92,21 @@ fn emit_seal_statement(out: &mut String, statement: &Statement, indent: usize) {
             out.push_str(&join_values(argv, seal_value));
             out.push_str(")\n");
         }
+        Statement::CaptureFunction {
+            name,
+            function,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str(name);
+            out.push_str("=$(");
+            out.push_str(function);
+            if !argv.is_empty() {
+                out.push(' ');
+                out.push_str(&join_values(argv, seal_value));
+            }
+            out.push_str(")\n");
+        }
         Statement::If {
             predicate,
             then_body,
@@ -117,7 +152,12 @@ fn emit_seal_statement(out: &mut String, statement: &Statement, indent: usize) {
     }
 }
 
-fn emit_seal_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
+fn emit_seal_argv_parse(
+    out: &mut String,
+    specs: &[ArgvSpec],
+    positional: Option<&ArgvPositional>,
+    indent: usize,
+) {
     let pad = "  ".repeat(indent);
     out.push_str(&format!("{pad}__seal_argc=$#\n"));
     out.push_str(&format!("{pad}__seal_help=false\n"));
@@ -128,6 +168,12 @@ fn emit_seal_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
         };
         out.push_str(&format!("{pad}{}={value}\n", spec.name));
     }
+    if let Some(positional) = positional {
+        out.push_str(&format!(
+            "{pad}{}={}\n",
+            positional.name, positional.default
+        ));
+    }
     out.push_str(&format!("{pad}while [ \"$#\" -gt 0 ]; do\n"));
     out.push_str(&format!("{pad}  case \"$1\" in\n"));
     for spec in specs {
@@ -144,7 +190,24 @@ fn emit_seal_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
     out.push_str(&format!("{pad}      __seal_help=true\n"));
     out.push_str(&format!("{pad}      shift\n"));
     out.push_str(&format!("{pad}      ;;\n"));
-    out.push_str(&format!("{pad}    *) fail \"unknown option: $1\" ;;\n"));
+    if let Some(positional) = positional {
+        out.push_str(&format!("{pad}    *)\n"));
+        out.push_str(&format!(
+            "{pad}      if [ -z \"${}\" ]; then\n",
+            positional.name
+        ));
+        out.push_str(&format!("{pad}        {}=$1\n", positional.name));
+        out.push_str(&format!("{pad}        shift\n"));
+        out.push_str(&format!("{pad}      else\n"));
+        out.push_str(&format!(
+            "{pad}        fail \"{}\"\n",
+            positional.extra_error
+        ));
+        out.push_str(&format!("{pad}      fi\n"));
+        out.push_str(&format!("{pad}      ;;\n"));
+    } else {
+        out.push_str(&format!("{pad}    *) fail \"unknown option: $1\" ;;\n"));
+    }
     out.push_str(&format!("{pad}  esac\n"));
     out.push_str(&format!("{pad}done\n"));
 }
@@ -218,6 +281,25 @@ fn emit_bash_statement(out: &mut String, statement: &Statement, indent: usize) {
         Statement::Assign { name, value } => {
             out.push_str(&format!("{pad}{name}={}\n", bash_value(value)));
         }
+        Statement::ExecWrite {
+            stream,
+            path,
+            append,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str(&join_values(argv, bash_value));
+            out.push(' ');
+            out.push_str(match (stream, append) {
+                (OutputStream::Stdout, false) => ">",
+                (OutputStream::Stdout, true) => ">>",
+                (OutputStream::Stderr, false) => "2>",
+                (OutputStream::Stderr, true) => "2>>",
+            });
+            out.push(' ');
+            out.push_str(&bash_value(path));
+            out.push('\n');
+        }
         Statement::ExecChecked { argv } => {
             out.push_str(&pad);
             out.push_str(&join_values(argv, bash_value));
@@ -243,7 +325,9 @@ fn emit_bash_statement(out: &mut String, statement: &Statement, indent: usize) {
             }
             out.push('\n');
         }
-        Statement::ArgvParse { specs } => emit_bash_argv_parse(out, specs, indent),
+        Statement::ArgvParse { specs, positional } => {
+            emit_bash_argv_parse(out, specs, positional.as_ref(), indent)
+        }
         Statement::CaptureChecked { name, argv } => {
             out.push_str(&pad);
             out.push_str(name);
@@ -251,6 +335,21 @@ fn emit_bash_statement(out: &mut String, statement: &Statement, indent: usize) {
             out.push_str(&join_values(argv, bash_value));
             out.push_str(")\n");
         }
+        Statement::CaptureFunction {
+            name,
+            function,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str(name);
+            out.push_str("=$(");
+            out.push_str(function);
+            if !argv.is_empty() {
+                out.push(' ');
+                out.push_str(&join_values(argv, bash_value));
+            }
+            out.push_str(")\n");
+        }
         Statement::If {
             predicate,
             then_body,
@@ -302,7 +401,12 @@ fn emit_bash_statement(out: &mut String, statement: &Statement, indent: usize) {
     }
 }
 
-fn emit_bash_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
+fn emit_bash_argv_parse(
+    out: &mut String,
+    specs: &[ArgvSpec],
+    positional: Option<&ArgvPositional>,
+    indent: usize,
+) {
     let pad = "  ".repeat(indent);
     out.push_str(&format!("{pad}__seal_argc=$#\n"));
     out.push_str(&format!("{pad}__seal_help=false\n"));
@@ -313,6 +417,13 @@ fn emit_bash_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
         };
         out.push_str(&format!("{pad}{}={value}\n", spec.name));
     }
+    if let Some(positional) = positional {
+        out.push_str(&format!(
+            "{pad}{}={}\n",
+            positional.name,
+            sh_quote(&positional.default)
+        ));
+    }
     out.push_str(&format!("{pad}while [ \"$#\" -gt 0 ]; do\n"));
     out.push_str(&format!("{pad}  case \"$1\" in\n"));
     for spec in specs {
@@ -329,9 +440,26 @@ fn emit_bash_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
     out.push_str(&format!("{pad}      __seal_help=true\n"));
     out.push_str(&format!("{pad}      shift\n"));
     out.push_str(&format!("{pad}      ;;\n"));
-    out.push_str(&format!(
-        "{pad}    *) seal_fail \"unknown option: $1\" ;;\n"
-    ));
+    if let Some(positional) = positional {
+        out.push_str(&format!("{pad}    *)\n"));
+        out.push_str(&format!(
+            "{pad}      if [ -z \"${}\" ]; then\n",
+            positional.name
+        ));
+        out.push_str(&format!("{pad}        {}=$1\n", positional.name));
+        out.push_str(&format!("{pad}        shift\n"));
+        out.push_str(&format!("{pad}      else\n"));
+        out.push_str(&format!(
+            "{pad}        seal_fail \"{}\"\n",
+            positional.extra_error
+        ));
+        out.push_str(&format!("{pad}      fi\n"));
+        out.push_str(&format!("{pad}      ;;\n"));
+    } else {
+        out.push_str(&format!(
+            "{pad}    *) seal_fail \"unknown option: $1\" ;;\n"
+        ));
+    }
     out.push_str(&format!("{pad}  esac\n"));
     out.push_str(&format!("{pad}done\n"));
 }
diff --git a/app/src/core/transpile/emit/powershell.rs b/app/src/core/transpile/emit/powershell.rs
index 4ee31a3..2947eb8 100644
--- a/app/src/core/transpile/emit/powershell.rs
+++ b/app/src/core/transpile/emit/powershell.rs
@@ -1,8 +1,13 @@
-use super::support::{generated_header, option_name};
+use super::powershell_support::{emit_positional_bindings, max_positional_statements};
+use super::support::generated_header;
 use crate::core::transpile::ast::{
-    ArgvKind, ArgvSpec, EnvAssign, Item, Predicate, Program, Statement, Value,
+    EnvAssign, ExpansionOp, Item, OutputStream, Predicate, Program, Statement, Value, ValueSource,
 };
 
+#[path = "powershell_argv.rs"]
+mod powershell_argv;
+use self::powershell_argv::emit_argv_parse;
+
 pub(crate) fn emit_powershell(program: &Program, source_name: Option<&str>) -> String {
     let mut out = generated_header("powershell", source_name);
     out.push_str("$ErrorActionPreference = 'Stop'\n\n");
@@ -59,6 +64,26 @@ fn emit_statement(out: &mut String, statement: &Statement, indent: usize, positi
         Statement::Assign { name, value } => {
             out.push_str(&format!("{pad}${name} = {}\n", powershell_value(value)));
         }
+        Statement::ExecWrite {
+            stream,
+            path,
+            append,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str("& ");
+            out.push_str(&join_values(argv, powershell_value));
+            out.push(' ');
+            out.push_str(match (stream, append) {
+                (OutputStream::Stdout, false) => ">",
+                (OutputStream::Stdout, true) => ">>",
+                (OutputStream::Stderr, false) => "2>",
+                (OutputStream::Stderr, true) => "2>>",
+            });
+            out.push(' ');
+            out.push_str(&powershell_value(path));
+            out.push('\n');
+        }
         Statement::ExecChecked { argv } => {
             out.push_str(&pad);
             out.push_str("& ");
@@ -76,13 +101,28 @@ fn emit_statement(out: &mut String, statement: &Statement, indent: usize, positi
             }
             emit_positional_bindings(out, indent, positional_max);
         }
-        Statement::ArgvParse { specs } => emit_argv_parse(out, specs, indent),
+        Statement::ArgvParse { specs, positional } => {
+            emit_argv_parse(out, specs, positional.as_ref(), indent)
+        }
         Statement::CaptureChecked { name, argv } => {
             out.push_str(&pad);
             out.push_str(&format!("${name} = & "));
             out.push_str(&join_values(argv, powershell_value));
             out.push('\n');
         }
+        Statement::CaptureFunction {
+            name,
+            function,
+            argv,
+        } => {
+            out.push_str(&pad);
+            out.push_str(&format!("${name} = & {function}"));
+            if !argv.is_empty() {
+                out.push(' ');
+                out.push_str(&join_values(argv, powershell_value));
+            }
+            out.push('\n');
+        }
         Statement::If {
             predicate,
             then_body,
@@ -137,97 +177,6 @@ fn emit_statement(out: &mut String, statement: &Statement, indent: usize, positi
     }
 }
 
-fn emit_positional_bindings(out: &mut String, indent: usize, max: usize) -> bool {
-    if max == 0 {
-        return false;
-    }
-    let pad = "    ".repeat(indent);
-    out.push_str(&format!("{pad}$0 = $args.Count\n"));
-    for index in 1..=max {
-        let offset = index - 1;
-        out.push_str(&format!(
-            "{pad}${index} = if ($args.Count -ge {index}) {{ $args[{offset}] }} else {{ '' }}\n"
-        ));
-    }
-    true
-}
-
-fn emit_argv_parse(out: &mut String, specs: &[ArgvSpec], indent: usize) {
-    let pad = "    ".repeat(indent);
-    out.push_str(&format!("{pad}$__seal_argc = $args.Count\n"));
-    out.push_str(&format!("{pad}$__seal_help = 'false'\n"));
-    for spec in specs {
-        let value = match spec.kind {
-            ArgvKind::String => powershell_quote(spec.default.as_deref().unwrap_or("")),
-            ArgvKind::Flag => "'false'".to_string(),
-        };
-        out.push_str(&format!("{pad}${} = {value}\n", spec.name));
-    }
-    out.push_str(&format!("{pad}$__seal_index = 0\n"));
-    out.push_str(&format!("{pad}while ($__seal_index -lt $args.Count) {{\n"));
-    out.push_str(&format!("{pad}    $__seal_arg = $args[$__seal_index]\n"));
-    out.push_str(&format!("{pad}    switch -Regex ($__seal_arg) {{\n"));
-    for spec in specs {
-        match spec.kind {
-            ArgvKind::String => emit_string_option(out, spec, indent),
-            ArgvKind::Flag => emit_flag_option(out, spec, indent),
-        }
-    }
-    out.push_str(&format!("{pad}        '^--$' {{\n"));
-    out.push_str(&format!("{pad}            $__seal_index = $args.Count\n"));
-    out.push_str(&format!("{pad}            break\n"));
-    out.push_str(&format!("{pad}        }}\n"));
-    out.push_str(&format!("{pad}        '^(-h|--help|help)$' {{\n"));
-    out.push_str(&format!("{pad}            $__seal_help = 'true'\n"));
-    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
-    out.push_str(&format!("{pad}            break\n"));
-    out.push_str(&format!("{pad}        }}\n"));
-    out.push_str(&format!(
-        "{pad}        default {{ throw \"unknown option: $__seal_arg\" }}\n"
-    ));
-    out.push_str(&format!("{pad}    }}\n"));
-    out.push_str(&format!("{pad}}}\n"));
-}
-
-fn emit_string_option(out: &mut String, spec: &ArgvSpec, indent: usize) {
-    let pad = "    ".repeat(indent);
-    let option = option_name(&spec.name);
-    out.push_str(&format!("{pad}        '^{}$' {{\n", regex_quote(&option)));
-    out.push_str(&format!(
-        "{pad}            if ($__seal_index + 1 -ge $args.Count) {{ throw 'missing value for {option}' }}\n"
-    ));
-    out.push_str(&format!(
-        "{pad}            ${} = $args[$__seal_index + 1]\n",
-        spec.name
-    ));
-    out.push_str(&format!("{pad}            $__seal_index += 2\n"));
-    out.push_str(&format!("{pad}            break\n"));
-    out.push_str(&format!("{pad}        }}\n"));
-    out.push_str(&format!("{pad}        '^{}=' {{\n", regex_quote(&option)));
-    out.push_str(&format!(
-        "{pad}            ${} = $__seal_arg.Substring({})\n",
-        spec.name,
-        option.len() + 1
-    ));
-    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
-    out.push_str(&format!("{pad}            break\n"));
-    out.push_str(&format!("{pad}        }}\n"));
-}
-
-fn emit_flag_option(out: &mut String, spec: &ArgvSpec, indent: usize) {
-    let pad = "    ".repeat(indent);
-    let option = option_name(&spec.name);
-    out.push_str(&format!("{pad}        '^{}$' {{\n", regex_quote(&option)));
-    out.push_str(&format!("{pad}            ${} = 'true'\n", spec.name));
-    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
-    out.push_str(&format!("{pad}            break\n"));
-    out.push_str(&format!("{pad}        }}\n"));
-}
-
-fn regex_quote(value: &str) -> String {
-    value.replace('-', "\\-")
-}
-
 fn emit_if(
     out: &mut String,
     pad: &str,
@@ -350,15 +299,8 @@ fn powershell_value(value: &Value) -> String {
     match value {
         Value::Literal { text } => powershell_quote(text),
         Value::Argc => "$args.Count".to_string(),
-        Value::Var { name } => format!("${name}"),
         Value::Args => "@args".to_string(),
-        Value::Env { name } => format!("$env:{name}"),
-        Value::EnvDefault { name, default } => {
-            format!(
-                "$(if ($env:{name}) {{ $env:{name} }} else {{ {} }})",
-                powershell_quote(default)
-            )
-        }
+        Value::Expand { source, op } => powershell_expand(source, op),
         Value::Concat { parts } => {
             if parts.is_empty() {
                 return "''".to_string();
@@ -373,49 +315,45 @@ fn powershell_value(value: &Value) -> String {
     }
 }
 
-fn max_positional_statements<'a>(statements: impl IntoIterator<Item = &'a Statement>) -> usize {
-    statements
-        .into_iter()
-        .map(max_positional_statement)
-        .max()
-        .unwrap_or_default()
+fn powershell_expand(source: &ValueSource, op: &ExpansionOp) -> String {
+    match op {
+        ExpansionOp::Plain => powershell_source_value(source),
+        ExpansionOp::DefaultIfUnsetOrEmpty { fallback } => {
+            powershell_guarded_expand(source, fallback, false)
+        }
+        ExpansionOp::RequireNonEmpty { message } => {
+            powershell_guarded_expand(source, message, true)
+        }
+    }
 }
 
-fn max_positional_statement(statement: &Statement) -> usize {
-    match statement {
-        Statement::Assign { value, .. } => max_positional_value(value),
-        Statement::ExecChecked { argv }
-        | Statement::EnvExecChecked { argv, .. }
-        | Statement::CaptureChecked { argv, .. }
-        | Statement::CallFunction { argv, .. } => argv
-            .iter()
-            .map(max_positional_value)
-            .max()
-            .unwrap_or_default(),
-        Statement::If {
-            predicate,
-            then_body,
-            else_body,
-        } => max_positional_predicate(predicate)
-            .max(max_positional_statements(then_body.iter()))
-            .max(max_positional_statements(else_body.iter())),
-        Statement::While { predicate, body } => {
-            max_positional_predicate(predicate).max(max_positional_statements(body.iter()))
+fn powershell_source_value(source: &ValueSource) -> String {
+    match source {
+        ValueSource::Var { name } => format!("${name}"),
+        ValueSource::Env { name } => format!("$env:{name}"),
+    }
+}
+
+fn powershell_guarded_expand(source: &ValueSource, text: &str, require: bool) -> String {
+    let fallback_or_message = powershell_quote(text);
+    let action = if require {
+        format!("throw {fallback_or_message}")
+    } else {
+        fallback_or_message
+    };
+    match source {
+        ValueSource::Env { name } => format!(
+            "$(if ([string]::IsNullOrEmpty($env:{name})) {{ {action} }} else {{ $env:{name} }})"
+        ),
+        ValueSource::Var { name } if name.bytes().all(|byte| byte.is_ascii_digit()) => {
+            let index = name.parse::<usize>().unwrap_or_default();
+            format!(
+                "$(if (($args.Count -lt {index}) -or [string]::IsNullOrEmpty(${name})) {{ {action} }} else {{ ${name} }})"
+            )
         }
-        Statement::Case { value, arms } => arms
-            .iter()
-            .map(|arm| max_positional_statements(arm.body.iter()))
-            .max()
-            .unwrap_or_default()
-            .max(max_positional_value(value)),
-        Statement::Print { value } | Statement::Error { value } | Statement::Fail { value } => {
-            max_positional_value(value)
+        ValueSource::Var { name } => {
+            format!("$(if ([string]::IsNullOrEmpty(${name})) {{ {action} }} else {{ ${name} }})")
         }
-        Statement::ArgvParse { .. }
-        | Statement::Shift { .. }
-        | Statement::Exit { .. }
-        | Statement::Break
-        | Statement::Sleep { .. } => 0,
     }
 }
 
@@ -449,47 +387,6 @@ fn emit_env_exec(out: &mut String, pad: &str, env: &[EnvAssign], argv: &[Value])
     out.push_str(&format!("{pad}}}\n"));
 }
 
-fn max_positional_predicate(predicate: &Predicate) -> usize {
-    match predicate {
-        Predicate::Command { argv } => argv
-            .iter()
-            .map(max_positional_value)
-            .max()
-            .unwrap_or_default(),
-        Predicate::Empty { value }
-        | Predicate::NotEmpty { value }
-        | Predicate::JsonEmpty { value }
-        | Predicate::JsonNotEmpty { value } => max_positional_value(value),
-        Predicate::Eq { left, right }
-        | Predicate::Neq { left, right }
-        | Predicate::IntLt { left, right }
-        | Predicate::IntLte { left, right }
-        | Predicate::IntGt { left, right }
-        | Predicate::IntGte { left, right } => {
-            max_positional_value(left).max(max_positional_value(right))
-        }
-        Predicate::FileExists { path } | Predicate::DirExists { path } => {
-            max_positional_value(path)
-        }
-    }
-}
-
-fn max_positional_value(value: &Value) -> usize {
-    match value {
-        Value::Var { name } => name.parse::<usize>().unwrap_or_default(),
-        Value::Concat { parts } => parts
-            .iter()
-            .map(max_positional_value)
-            .max()
-            .unwrap_or_default(),
-        Value::Literal { .. }
-        | Value::Argc
-        | Value::Args
-        | Value::Env { .. }
-        | Value::EnvDefault { .. } => 0,
-    }
-}
-
 fn join_values(values: &[Value], format: fn(&Value) -> String) -> String {
     values.iter().map(format).collect::<Vec<_>>().join(" ")
 }
diff --git a/app/src/core/transpile/emit/powershell_argv.rs b/app/src/core/transpile/emit/powershell_argv.rs
new file mode 100644
index 0000000..0108e2b
--- /dev/null
+++ b/app/src/core/transpile/emit/powershell_argv.rs
@@ -0,0 +1,113 @@
+use crate::core::transpile::ast::{ArgvKind, ArgvPositional, ArgvSpec};
+use crate::core::transpile::emit::support::option_name;
+
+use super::powershell_quote;
+
+pub(super) fn emit_argv_parse(
+    out: &mut String,
+    specs: &[ArgvSpec],
+    positional: Option<&ArgvPositional>,
+    indent: usize,
+) {
+    let pad = "    ".repeat(indent);
+    out.push_str(&format!("{pad}$__seal_argc = $args.Count\n"));
+    out.push_str(&format!("{pad}$__seal_help = 'false'\n"));
+    for spec in specs {
+        let value = match spec.kind {
+            ArgvKind::String => powershell_quote(spec.default.as_deref().unwrap_or("")),
+            ArgvKind::Flag => "'false'".to_string(),
+        };
+        out.push_str(&format!("{pad}${} = {value}\n", spec.name));
+    }
+    if let Some(positional) = positional {
+        out.push_str(&format!(
+            "{pad}${} = {}\n",
+            positional.name,
+            powershell_quote(&positional.default)
+        ));
+    }
+    out.push_str(&format!("{pad}$__seal_index = 0\n"));
+    out.push_str(&format!("{pad}while ($__seal_index -lt $args.Count) {{\n"));
+    out.push_str(&format!("{pad}    $__seal_arg = $args[$__seal_index]\n"));
+    out.push_str(&format!("{pad}    switch -Regex ($__seal_arg) {{\n"));
+    for spec in specs {
+        match spec.kind {
+            ArgvKind::String => emit_string_option(out, spec, indent),
+            ArgvKind::Flag => emit_flag_option(out, spec, indent),
+        }
+    }
+    out.push_str(&format!("{pad}        '^--$' {{\n"));
+    out.push_str(&format!("{pad}            $__seal_index = $args.Count\n"));
+    out.push_str(&format!("{pad}            break\n"));
+    out.push_str(&format!("{pad}        }}\n"));
+    out.push_str(&format!("{pad}        '^(-h|--help|help)$' {{\n"));
+    out.push_str(&format!("{pad}            $__seal_help = 'true'\n"));
+    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
+    out.push_str(&format!("{pad}            break\n"));
+    out.push_str(&format!("{pad}        }}\n"));
+    if let Some(positional) = positional {
+        out.push_str(&format!("{pad}        default {{\n"));
+        out.push_str(&format!(
+            "{pad}            if ([string]::IsNullOrEmpty(${})) {{\n",
+            positional.name
+        ));
+        out.push_str(&format!(
+            "{pad}                ${} = $__seal_arg\n",
+            positional.name
+        ));
+        out.push_str(&format!("{pad}                $__seal_index += 1\n"));
+        out.push_str(&format!("{pad}                break\n"));
+        out.push_str(&format!("{pad}            }} else {{\n"));
+        out.push_str(&format!(
+            "{pad}                throw \"{}\"\n",
+            positional.extra_error.replace("$1", "$__seal_arg")
+        ));
+        out.push_str(&format!("{pad}            }}\n"));
+        out.push_str(&format!("{pad}        }}\n"));
+    } else {
+        out.push_str(&format!(
+            "{pad}        default {{ throw \"unknown option: $__seal_arg\" }}\n"
+        ));
+    }
+    out.push_str(&format!("{pad}    }}\n"));
+    out.push_str(&format!("{pad}}}\n"));
+}
+
+fn emit_string_option(out: &mut String, spec: &ArgvSpec, indent: usize) {
+    let pad = "    ".repeat(indent);
+    let option = option_name(&spec.name);
+    out.push_str(&format!("{pad}        '^{}$' {{\n", regex_quote(&option)));
+    out.push_str(&format!(
+        "{pad}            if ($__seal_index + 1 -ge $args.Count) {{ throw 'missing value for {option}' }}\n"
+    ));
+    out.push_str(&format!(
+        "{pad}            ${} = $args[$__seal_index + 1]\n",
+        spec.name
+    ));
+    out.push_str(&format!("{pad}            $__seal_index += 2\n"));
+    out.push_str(&format!("{pad}            break\n"));
+    out.push_str(&format!("{pad}        }}\n"));
+    out.push_str(&format!("{pad}        '^{}=' {{\n", regex_quote(&option)));
+    out.push_str(&format!(
+        "{pad}            ${} = $__seal_arg.Substring({})\n",
+        spec.name,
+        option.len() + 1
+    ));
+    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
+    out.push_str(&format!("{pad}            break\n"));
+    out.push_str(&format!("{pad}        }}\n"));
+}
+
+fn emit_flag_option(out: &mut String, spec: &ArgvSpec, indent: usize) {
+    let pad = "    ".repeat(indent);
+    let option = option_name(&spec.name);
+    out.push_str(&format!("{pad}        '^{}$' {{\n", regex_quote(&option)));
+    out.push_str(&format!("{pad}            ${} = 'true'\n", spec.name));
+    out.push_str(&format!("{pad}            $__seal_index += 1\n"));
+    out.push_str(&format!("{pad}            break\n"));
+    out.push_str(&format!("{pad}        }}\n"));
+}
+
+fn regex_quote(value: &str) -> String {
+    value.replace('-', "\\-")
+}
diff --git a/app/src/core/transpile/emit/powershell_support.rs b/app/src/core/transpile/emit/powershell_support.rs
new file mode 100644
index 0000000..30a39bb
--- /dev/null
+++ b/app/src/core/transpile/emit/powershell_support.rs
@@ -0,0 +1,120 @@
+use crate::core::transpile::ast::{ExpansionOp, Predicate, Statement, Value, ValueSource};
+
+pub(super) fn emit_positional_bindings(out: &mut String, indent: usize, max: usize) -> bool {
+    if max == 0 {
+        return false;
+    }
+    let pad = "    ".repeat(indent);
+    out.push_str(&format!("{pad}$0 = $args.Count\n"));
+    for index in 1..=max {
+        let offset = index - 1;
+        out.push_str(&format!(
+            "{pad}${index} = if ($args.Count -ge {index}) {{ $args[{offset}] }} else {{ '' }}\n"
+        ));
+    }
+    true
+}
+
+pub(super) fn max_positional_statements<'a>(
+    statements: impl IntoIterator<Item = &'a Statement>,
+) -> usize {
+    statements
+        .into_iter()
+        .map(max_positional_statement)
+        .max()
+        .unwrap_or_default()
+}
+
+fn max_positional_statement(statement: &Statement) -> usize {
+    match statement {
+        Statement::Assign { value, .. } => max_positional_value(value),
+        Statement::ExecWrite { argv, path, .. } => argv
+            .iter()
+            .map(max_positional_value)
+            .max()
+            .unwrap_or_default()
+            .max(max_positional_value(path)),
+        Statement::ExecChecked { argv }
+        | Statement::EnvExecChecked { argv, .. }
+        | Statement::CaptureChecked { argv, .. }
+        | Statement::CaptureFunction { argv, .. }
+        | Statement::CallFunction { argv, .. } => argv
+            .iter()
+            .map(max_positional_value)
+            .max()
+            .unwrap_or_default(),
+        Statement::If {
+            predicate,
+            then_body,
+            else_body,
+        } => max_positional_predicate(predicate)
+            .max(max_positional_statements(then_body.iter()))
+            .max(max_positional_statements(else_body.iter())),
+        Statement::While { predicate, body } => {
+            max_positional_predicate(predicate).max(max_positional_statements(body.iter()))
+        }
+        Statement::Case { value, arms } => arms
+            .iter()
+            .map(|arm| max_positional_statements(arm.body.iter()))
+            .max()
+            .unwrap_or_default()
+            .max(max_positional_value(value)),
+        Statement::Print { value } | Statement::Error { value } | Statement::Fail { value } => {
+            max_positional_value(value)
+        }
+        Statement::ArgvParse { .. }
+        | Statement::Shift { .. }
+        | Statement::Exit { .. }
+        | Statement::Break
+        | Statement::Sleep { .. } => 0,
+    }
+}
+
+fn max_positional_predicate(predicate: &Predicate) -> usize {
+    match predicate {
+        Predicate::Command { argv } => argv
+            .iter()
+            .map(max_positional_value)
+            .max()
+            .unwrap_or_default(),
+        Predicate::Empty { value }
+        | Predicate::NotEmpty { value }
+        | Predicate::JsonEmpty { value }
+        | Predicate::JsonNotEmpty { value } => max_positional_value(value),
+        Predicate::Eq { left, right }
+        | Predicate::Neq { left, right }
+        | Predicate::IntLt { left, right }
+        | Predicate::IntLte { left, right }
+        | Predicate::IntGt { left, right }
+        | Predicate::IntGte { left, right } => {
+            max_positional_value(left).max(max_positional_value(right))
+        }
+        Predicate::FileExists { path } | Predicate::DirExists { path } => {
+            max_positional_value(path)
+        }
+    }
+}
+
+fn max_positional_value(value: &Value) -> usize {
+    match value {
+        Value::Expand { source, op } => max_positional_expand(source, op),
+        Value::Concat { parts } => parts
+            .iter()
+            .map(max_positional_value)
+            .max()
+            .unwrap_or_default(),
+        Value::Literal { .. } | Value::Argc | Value::Args => 0,
+    }
+}
+
+fn max_positional_expand(source: &ValueSource, op: &ExpansionOp) -> usize {
+    let source_max = match source {
+        ValueSource::Var { name } => name.parse::<usize>().unwrap_or_default(),
+        ValueSource::Env { .. } => 0,
+    };
+    match op {
+        ExpansionOp::Plain
+        | ExpansionOp::DefaultIfUnsetOrEmpty { .. }
+        | ExpansionOp::RequireNonEmpty { .. } => source_max,
+    }
+}
diff --git a/app/src/core/transpile/emit/support.rs b/app/src/core/transpile/emit/support.rs
index e5a0335..458f91c 100644
--- a/app/src/core/transpile/emit/support.rs
+++ b/app/src/core/transpile/emit/support.rs
@@ -1,4 +1,4 @@
-use crate::core::transpile::ast::{Predicate, Value};
+use crate::core::transpile::ast::{ExpansionOp, Predicate, Value, ValueSource};
 
 pub(super) fn option_name(name: &str) -> String {
     format!("--{}", name.replace('_', "-"))
@@ -57,10 +57,8 @@ pub(super) fn seal_value(value: &Value) -> String {
     match value {
         Value::Literal { text } => sh_quote(text),
         Value::Argc => "$#".to_string(),
-        Value::Var { name } => format!("${name}"),
         Value::Args => "\"$@\"".to_string(),
-        Value::Env { name } => format!("${{{name}}}"),
-        Value::EnvDefault { name, default } => format!("${{{name}:-{default}}}"),
+        Value::Expand { source, op } => seal_expand(source, op),
         Value::Concat { parts } => {
             let inner = parts
                 .iter()
@@ -80,20 +78,16 @@ pub(super) fn bash_value(value: &Value) -> String {
     match value {
         Value::Literal { text } => sh_quote(text),
         Value::Argc => "\"$#\"".to_string(),
-        Value::Var { name } => format!("\"${name}\""),
         Value::Args => "\"$@\"".to_string(),
-        Value::Env { name } => format!("\"${{{name}}}\""),
-        Value::EnvDefault { name, default } => format!("\"${{{name}:-{default}}}\""),
+        Value::Expand { source, op } => format!("\"{}\"", seal_expand(source, op)),
         Value::Concat { parts } => double_quote(
             &parts
                 .iter()
                 .map(|part| match part {
                     Value::Literal { text } => text.clone(),
                     Value::Argc => "$#".to_string(),
-                    Value::Var { name } => format!("${name}"),
                     Value::Args => "$@".to_string(),
-                    Value::Env { name } => format!("${{{name}}}"),
-                    Value::EnvDefault { name, default } => format!("${{{name}:-{default}}}"),
+                    Value::Expand { source, op } => seal_expand(source, op),
                     Value::Concat { .. } => bash_value(part),
                 })
                 .collect::<String>(),
@@ -104,15 +98,31 @@ pub(super) fn bash_value(value: &Value) -> String {
 pub(super) fn bash_int_value(value: &Value) -> String {
     match value {
         Value::Argc => "$#".to_string(),
-        Value::Var { name } => format!("${name}"),
         Value::Args => "\"$@\"".to_string(),
-        Value::Env { name } => format!("${{{name}}}"),
-        Value::EnvDefault { name, default } => format!("${{{name}:-{default}}}"),
+        Value::Expand { source, op } => seal_expand(source, op),
         Value::Literal { text } => sh_quote(text),
         Value::Concat { .. } => bash_value(value),
     }
 }
 
+fn seal_expand(source: &ValueSource, op: &ExpansionOp) -> String {
+    let name = match source {
+        ValueSource::Var { name } | ValueSource::Env { name } => name,
+    };
+    match op {
+        ExpansionOp::Plain => match source {
+            ValueSource::Var { .. } => format!("${name}"),
+            ValueSource::Env { .. } => format!("${{{name}}}"),
+        },
+        ExpansionOp::DefaultIfUnsetOrEmpty { fallback } => {
+            format!("${{{name}:-{fallback}}}")
+        }
+        ExpansionOp::RequireNonEmpty { message } => {
+            format!("${{{name}:?{message}}}")
+        }
+    }
+}
+
 pub(super) fn sh_quote(value: &str) -> String {
     if value.is_empty() {
         return "''".to_string();
diff --git a/app/src/core/transpile/frontend/powershell.rs b/app/src/core/transpile/frontend/powershell.rs
index 09988ea..4f67d91 100644
--- a/app/src/core/transpile/frontend/powershell.rs
+++ b/app/src/core/transpile/frontend/powershell.rs
@@ -1,8 +1,17 @@
 use anyhow::{Result, bail};
 
+#[path = "powershell_value.rs"]
+mod powershell_value;
+
+pub(crate) use self::powershell_value::parse_value;
+use self::powershell_value::{
+    assignment, is_generated_positional_binding, parse_argv, parse_pattern, strip_comment,
+    validate_name,
+};
 use super::predicate::parse_powershell_predicate;
 use crate::core::transpile::ast::{CaseArm, Item, Program, Statement, Value};
 use crate::core::transpile::lower::lower_functions;
+use crate::core::transpile::parse_lex::is_valid_name;
 
 #[derive(Debug, Clone)]
 struct Line {
@@ -29,6 +38,7 @@ impl Parser {
                 if text.is_empty()
                     || text.starts_with("# Generated by ")
                     || text == "$ErrorActionPreference = 'Stop'"
+                    || is_generated_positional_binding(&text)
                 {
                     return None;
                 }
@@ -234,10 +244,7 @@ fn parse_simple_statement(line: &Line) -> Result<Statement> {
     }
     if let Some(argv) = line.text.strip_prefix("& ") {
         return Ok(Statement::ExecChecked {
-            argv: split_exprs(argv, line.number)?
-                .iter()
-                .map(|arg| parse_value(arg, line.number))
-                .collect::<Result<Vec<_>>>()?,
+            argv: parse_argv(argv, line.number)?,
         });
     }
     if is_valid_name(&line.text) {
@@ -253,179 +260,3 @@ fn parse_simple_statement(line: &Line) -> Result<Statement> {
         line.text
     )
 }
-
-fn parse_argv(text: &str, line: usize) -> Result<Vec<Value>> {
-    split_exprs(text, line)?
-        .iter()
-        .map(|arg| parse_argv_value(arg, line))
-        .collect::<Result<Vec<_>>>()
-}
-
-fn parse_argv_value(text: &str, line: usize) -> Result<Value> {
-    parse_value(text, line).or_else(|_| {
-        if is_valid_name(text) {
-            Ok(Value::Literal {
-                text: text.to_string(),
-            })
-        } else {
-            bail!("{line}: unsupported PowerShell argv value: {text}")
-        }
-    })
-}
-
-fn assignment(text: &str) -> Option<(String, &str)> {
-    let (name, value) = text.split_once(" = ")?;
-    let name = name.strip_prefix('$')?;
-    is_valid_name(name).then_some((name.to_string(), value))
-}
-
-pub(super) fn parse_value(text: &str, line: usize) -> Result<Value> {
-    let text = text.trim();
-    if let Some(value) = text
-        .strip_prefix('\'')
-        .and_then(|value| value.strip_suffix('\''))
-    {
-        return Ok(Value::Literal {
-            text: value.replace("''", "'"),
-        });
-    }
-    if let Some((name, default)) = env_default(text) {
-        validate_name(name, line)?;
-        return Ok(Value::EnvDefault {
-            name: name.to_string(),
-            default: default.to_string(),
-        });
-    }
-    if let Some(name) = text.strip_prefix("$env:") {
-        validate_name(name, line)?;
-        return Ok(Value::Env {
-            name: name.to_string(),
-        });
-    }
-    if let Some(name) = text.strip_prefix('$') {
-        validate_name(name, line)?;
-        return Ok(Value::Var {
-            name: name.to_string(),
-        });
-    }
-    if text.bytes().all(|byte| byte.is_ascii_digit()) {
-        return Ok(Value::Literal {
-            text: text.to_string(),
-        });
-    }
-    if let Some(inner) = text
-        .strip_prefix('(')
-        .and_then(|value| value.strip_suffix(')'))
-        && inner.contains(" + ")
-    {
-        return Ok(Value::Concat {
-            parts: split_concat(inner, line)?
-                .iter()
-                .map(|part| parse_value(part, line))
-                .collect::<Result<Vec<_>>>()?,
-        });
-    }
-    bail!("{line}: unsupported PowerShell value: {text}")
-}
-
-fn env_default(text: &str) -> Option<(&str, &str)> {
-    let inner = text.strip_prefix("$(if ($env:")?;
-    let (name, rest) = inner.split_once(") { $env:")?;
-    let (name2, rest) = rest.split_once(" } else { ")?;
-    if name != name2 {
-        return None;
-    }
-    let default = rest.strip_suffix(" })")?;
-    let default = default.strip_prefix('\'')?.strip_suffix('\'')?;
-    Some((name, default))
-}
-
-fn split_exprs(text: &str, line: usize) -> Result<Vec<String>> {
-    split_top_level(text, line, ' ')
-}
-
-fn split_concat(text: &str, line: usize) -> Result<Vec<String>> {
-    split_top_level(text, line, '+').map(|items| {
-        items
-            .into_iter()
-            .map(|item| item.trim().to_string())
-            .collect()
-    })
-}
-
-fn split_top_level(text: &str, line: usize, delimiter: char) -> Result<Vec<String>> {
-    let mut items = Vec::new();
-    let mut current = String::new();
-    let mut quote = false;
-    let mut depth = 0usize;
-    for ch in text.chars() {
-        match ch {
-            '\'' => {
-                quote = !quote;
-                current.push(ch);
-            }
-            '(' if !quote => {
-                depth += 1;
-                current.push(ch);
-            }
-            ')' if !quote => {
-                depth = depth.saturating_sub(1);
-                current.push(ch);
-            }
-            ch if ch == delimiter && !quote && depth == 0 => {
-                if !current.trim().is_empty() {
-                    items.push(current.trim().to_string());
-                    current.clear();
-                }
-            }
-            _ => current.push(ch),
-        }
-    }
-    if quote {
-        bail!("{line}: unterminated PowerShell string");
-    }
-    if !current.trim().is_empty() {
-        items.push(current.trim().to_string());
-    }
-    Ok(items)
-}
-
-fn strip_comment(line: &str) -> String {
-    let mut output = String::new();
-    let mut quote = false;
-    for ch in line.chars() {
-        match ch {
-            '\'' => {
-                quote = !quote;
-                output.push(ch);
-            }
-            '#' if !quote => break,
-            _ => output.push(ch),
-        }
-    }
-    output
-}
-
-fn parse_pattern(pattern: &str) -> String {
-    if pattern == "Default" {
-        return "*".to_string();
-    }
-    pattern
-        .strip_prefix('\'')
-        .and_then(|value| value.strip_suffix('\''))
-        .unwrap_or(pattern)
-        .to_string()
-}
-
-fn validate_name(name: &str, line: usize) -> Result<()> {
-    if !is_valid_name(name) {
-        bail!("{line}: invalid PowerShell name: {name}");
-    }
-    Ok(())
-}
-
-fn is_valid_name(name: &str) -> bool {
-    let mut bytes = name.bytes();
-    matches!(bytes.next(), Some(byte) if byte.is_ascii_alphabetic() || byte == b'_')
-        && bytes.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
-}
diff --git a/app/src/core/transpile/frontend/powershell_value.rs b/app/src/core/transpile/frontend/powershell_value.rs
new file mode 100644
index 0000000..976ae60
--- /dev/null
+++ b/app/src/core/transpile/frontend/powershell_value.rs
@@ -0,0 +1,315 @@
+use anyhow::{Result, bail};
+
+use crate::core::transpile::ast::{ExpansionOp, Value, ValueSource};
+
+pub(super) fn parse_argv(text: &str, line: usize) -> Result<Vec<Value>> {
+    split_exprs(text, line)?
+        .iter()
+        .map(|arg| parse_argv_value(arg, line))
+        .collect::<Result<Vec<_>>>()
+}
+
+pub(crate) fn parse_value(text: &str, line: usize) -> Result<Value> {
+    let text = text.trim();
+    if let Some(value) = text
+        .strip_prefix('\'')
+        .and_then(|value| value.strip_suffix('\''))
+    {
+        return Ok(Value::Literal {
+            text: value.replace("''", "'"),
+        });
+    }
+    if let Some((source, op)) = guarded_expand(text, line)? {
+        return Ok(Value::Expand { source, op });
+    }
+    if let Some(name) = text.strip_prefix("$env:") {
+        validate_name(name, line)?;
+        return Ok(Value::Expand {
+            source: ValueSource::Env {
+                name: name.to_string(),
+            },
+            op: ExpansionOp::Plain,
+        });
+    }
+    if let Some(name) = text.strip_prefix('$') {
+        if is_valid_positional(name) {
+            return Ok(Value::Expand {
+                source: ValueSource::Var {
+                    name: name.to_string(),
+                },
+                op: ExpansionOp::Plain,
+            });
+        }
+        validate_name(name, line)?;
+        return Ok(Value::Expand {
+            source: ValueSource::Var {
+                name: name.to_string(),
+            },
+            op: ExpansionOp::Plain,
+        });
+    }
+    if text.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Ok(Value::Literal {
+            text: text.to_string(),
+        });
+    }
+    if let Some(inner) = text
+        .strip_prefix('(')
+        .and_then(|value| value.strip_suffix(')'))
+        && inner.contains(" + ")
+    {
+        return Ok(Value::Concat {
+            parts: split_concat(inner, line)?
+                .iter()
+                .map(|part| parse_value(part, line))
+                .collect::<Result<Vec<_>>>()?,
+        });
+    }
+    bail!("{line}: unsupported PowerShell value: {text}")
+}
+
+pub(super) fn assignment(text: &str) -> Option<(String, &str)> {
+    let (name, value) = text.split_once(" = ")?;
+    let name = name.strip_prefix('$')?;
+    is_valid_var_name(name).then_some((name.to_string(), value))
+}
+
+pub(super) fn parse_pattern(pattern: &str) -> String {
+    if pattern == "Default" {
+        return "*".to_string();
+    }
+    pattern
+        .strip_prefix('\'')
+        .and_then(|value| value.strip_suffix('\''))
+        .unwrap_or(pattern)
+        .to_string()
+}
+
+pub(super) fn strip_comment(line: &str) -> String {
+    let mut output = String::new();
+    let mut quote = false;
+    for ch in line.chars() {
+        match ch {
+            '\'' => {
+                quote = !quote;
+                output.push(ch);
+            }
+            '#' if !quote => break,
+            _ => output.push(ch),
+        }
+    }
+    output
+}
+
+pub(super) fn is_generated_positional_binding(text: &str) -> bool {
+    if text == "$0 = $args.Count" {
+        return true;
+    }
+    let Some(rest) = text.strip_prefix('$') else {
+        return false;
+    };
+    let Some((index, rest)) = rest.split_once(" = if ($args.Count -ge ") else {
+        return false;
+    };
+    let Some((index2, rest)) = rest.split_once(") { $args[") else {
+        return false;
+    };
+    let Some((offset, _rest)) = rest.split_once("] } else { '' }") else {
+        return false;
+    };
+    if index != index2 {
+        return false;
+    }
+    let Ok(index) = index.parse::<usize>() else {
+        return false;
+    };
+    let Ok(offset) = offset.parse::<usize>() else {
+        return false;
+    };
+    index.checked_sub(1) == Some(offset)
+}
+
+pub(super) fn validate_name(name: &str, line: usize) -> Result<()> {
+    if !is_valid_name(name) {
+        bail!("{line}: invalid PowerShell name: {name}");
+    }
+    Ok(())
+}
+
+fn parse_argv_value(text: &str, line: usize) -> Result<Value> {
+    parse_value(text, line).or_else(|_| {
+        if is_valid_name(text) {
+            Ok(Value::Literal {
+                text: text.to_string(),
+            })
+        } else {
+            bail!("{line}: unsupported PowerShell argv value: {text}")
+        }
+    })
+}
+
+fn guarded_expand(text: &str, line: usize) -> Result<Option<(ValueSource, ExpansionOp)>> {
+    let Some(inner) = text
+        .strip_prefix("$(if (")
+        .and_then(|value| value.strip_suffix(" })"))
+    else {
+        return Ok(None);
+    };
+    if let Some(parsed) = env_guarded_expand(inner, line)? {
+        return Ok(Some(parsed));
+    }
+    if let Some(parsed) = positional_guarded_expand(inner, line)? {
+        return Ok(Some(parsed));
+    }
+    if let Some(parsed) = var_guarded_expand(inner, line)? {
+        return Ok(Some(parsed));
+    }
+    Ok(None)
+}
+
+fn env_guarded_expand(text: &str, line: usize) -> Result<Option<(ValueSource, ExpansionOp)>> {
+    let Some(rest) = text.strip_prefix("[string]::IsNullOrEmpty($env:") else {
+        return Ok(None);
+    };
+    let (name, rest) = rest
+        .split_once(")) { ")
+        .ok_or_else(|| anyhow::anyhow!("{line}: unsupported PowerShell env expansion"))?;
+    validate_name(name, line)?;
+    let source = ValueSource::Env {
+        name: name.to_string(),
+    };
+    let plain = format!("$env:{name}");
+    parse_guarded_action(source, &plain, rest, line).map(Some)
+}
+
+fn positional_guarded_expand(
+    text: &str,
+    line: usize,
+) -> Result<Option<(ValueSource, ExpansionOp)>> {
+    let Some(rest) = text.strip_prefix("($args.Count -lt ") else {
+        return Ok(None);
+    };
+    let (index, rest) = rest
+        .split_once(") -or [string]::IsNullOrEmpty($")
+        .ok_or_else(|| anyhow::anyhow!("{line}: unsupported PowerShell positional expansion"))?;
+    let (name, rest) = rest
+        .split_once(")) { ")
+        .ok_or_else(|| anyhow::anyhow!("{line}: unsupported PowerShell positional expansion"))?;
+    if index != name {
+        bail!("{line}: unsupported PowerShell positional expansion");
+    }
+    let source = ValueSource::Var {
+        name: name.to_string(),
+    };
+    let plain = format!("${name}");
+    parse_guarded_action(source, &plain, rest, line).map(Some)
+}
+
+fn var_guarded_expand(text: &str, line: usize) -> Result<Option<(ValueSource, ExpansionOp)>> {
+    let Some(rest) = text.strip_prefix("[string]::IsNullOrEmpty($") else {
+        return Ok(None);
+    };
+    let (name, rest) = rest
+        .split_once(")) { ")
+        .ok_or_else(|| anyhow::anyhow!("{line}: unsupported PowerShell variable expansion"))?;
+    validate_name(name, line)?;
+    let source = ValueSource::Var {
+        name: name.to_string(),
+    };
+    let plain = format!("${name}");
+    parse_guarded_action(source, &plain, rest, line).map(Some)
+}
+
+fn parse_guarded_action(
+    source: ValueSource,
+    plain: &str,
+    rest: &str,
+    line: usize,
+) -> Result<(ValueSource, ExpansionOp)> {
+    let (action, expected_plain) = rest
+        .split_once(" } else { ")
+        .ok_or_else(|| anyhow::anyhow!("{line}: unsupported PowerShell guarded expansion"))?;
+    if expected_plain != plain {
+        bail!("{line}: unsupported PowerShell guarded expansion");
+    }
+    if let Some(message) = action.strip_prefix("throw ") {
+        let message = parse_single_quoted(message, line)?;
+        return Ok((source, ExpansionOp::RequireNonEmpty { message }));
+    }
+    let fallback = parse_single_quoted(action, line)?;
+    Ok((source, ExpansionOp::DefaultIfUnsetOrEmpty { fallback }))
+}
+
+fn parse_single_quoted(text: &str, line: usize) -> Result<String> {
+    let Some(value) = text
+        .strip_prefix('\'')
+        .and_then(|value| value.strip_suffix('\''))
+    else {
+        bail!("{line}: unsupported PowerShell quoted literal: {text}");
+    };
+    Ok(value.replace("''", "'"))
+}
+
+fn split_exprs(text: &str, line: usize) -> Result<Vec<String>> {
+    split_top_level(text, line, ' ')
+}
+
+fn split_concat(text: &str, line: usize) -> Result<Vec<String>> {
+    split_top_level(text, line, '+').map(|items| {
+        items
+            .into_iter()
+            .map(|item| item.trim().to_string())
+            .collect()
+    })
+}
+
+fn split_top_level(text: &str, line: usize, delimiter: char) -> Result<Vec<String>> {
+    let mut items = Vec::new();
+    let mut current = String::new();
+    let mut quote = false;
+    let mut depth = 0usize;
+    for ch in text.chars() {
+        match ch {
+            '\'' => {
+                quote = !quote;
+                current.push(ch);
+            }
+            '(' if !quote => {
+                depth += 1;
+                current.push(ch);
+            }
+            ')' if !quote => {
+                depth = depth.saturating_sub(1);
+                current.push(ch);
+            }
+            ch if ch == delimiter && !quote && depth == 0 => {
+                if !current.trim().is_empty() {
+                    items.push(current.trim().to_string());
+                    current.clear();
+                }
+            }
+            _ => current.push(ch),
+        }
+    }
+    if quote {
+        bail!("{line}: unterminated PowerShell string");
+    }
+    if !current.trim().is_empty() {
+        items.push(current.trim().to_string());
+    }
+    Ok(items)
+}
+
+fn is_valid_var_name(name: &str) -> bool {
+    is_valid_name(name) || is_valid_positional(name)
+}
+
+fn is_valid_name(name: &str) -> bool {
+    let mut bytes = name.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_alphabetic() || byte == b'_')
+        && bytes.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
+}
+
+fn is_valid_positional(name: &str) -> bool {
+    !name.is_empty() && name.bytes().all(|byte| byte.is_ascii_digit())
+}
diff --git a/app/src/core/transpile/guards.rs b/app/src/core/transpile/guards.rs
index 8f7341a..d1a807c 100644
--- a/app/src/core/transpile/guards.rs
+++ b/app/src/core/transpile/guards.rs
@@ -47,10 +47,12 @@ fn collect_bash_tool(statement: &Statement, tools: &mut BTreeSet<&'static str>)
         }
         Statement::Assign { .. }
         | Statement::ArgvParse { .. }
+        | Statement::ExecWrite { .. }
         | Statement::ExecChecked { .. }
         | Statement::EnvExecChecked { .. }
         | Statement::Shift { .. }
         | Statement::CaptureChecked { .. }
+        | Statement::CaptureFunction { .. }
         | Statement::CallFunction { .. }
         | Statement::Print { .. }
         | Statement::Error { .. }
diff --git a/app/src/core/transpile/lower.rs b/app/src/core/transpile/lower.rs
index 5c75598..b8d515a 100644
--- a/app/src/core/transpile/lower.rs
+++ b/app/src/core/transpile/lower.rs
@@ -38,6 +38,21 @@ fn lower_statement(statement: &mut Statement, functions: &BTreeSet<String>) {
                 *statement = Statement::CallFunction { name, argv };
             }
         }
+        Statement::CaptureChecked { name, argv } => {
+            let Some(Value::Literal { text }) = argv.first() else {
+                return;
+            };
+            if functions.contains(text) {
+                let destination = name.clone();
+                let function = text.clone();
+                let argv = argv[1..].to_vec();
+                *statement = Statement::CaptureFunction {
+                    name: destination,
+                    function,
+                    argv,
+                };
+            }
+        }
         Statement::If {
             then_body,
             else_body,
@@ -56,9 +71,10 @@ fn lower_statement(statement: &mut Statement, functions: &BTreeSet<String>) {
         }
         Statement::Assign { .. }
         | Statement::ArgvParse { .. }
+        | Statement::ExecWrite { .. }
         | Statement::EnvExecChecked { .. }
         | Statement::Shift { .. }
-        | Statement::CaptureChecked { .. }
+        | Statement::CaptureFunction { .. }
         | Statement::CallFunction { .. }
         | Statement::Print { .. }
         | Statement::Error { .. }
diff --git a/app/src/core/transpile/mod.rs b/app/src/core/transpile/mod.rs
index a569b6a..374e0e6 100644
--- a/app/src/core/transpile/mod.rs
+++ b/app/src/core/transpile/mod.rs
@@ -9,6 +9,7 @@ mod guards;
 mod lower;
 mod parse;
 mod parse_argv;
+mod parse_command;
 mod parse_lex;
 mod runner;
 mod value;
diff --git a/app/src/core/transpile/parse.rs b/app/src/core/transpile/parse.rs
index 367e11a..adc8945 100644
--- a/app/src/core/transpile/parse.rs
+++ b/app/src/core/transpile/parse.rs
@@ -3,6 +3,7 @@ use anyhow::{Result, bail};
 use super::ast::{CaseArm, EnvAssign, Item, Predicate, Program, Statement, Value};
 use super::lower::lower_functions;
 use super::parse_argv::parse_argv_block;
+use super::parse_command::{parse_exec_write, validate_external_tokens, validate_shell_command};
 use super::parse_lex::{
     assignment, is_safe_command_name, is_valid_name, split_test_words, split_words, strip_comment,
 };
@@ -231,6 +232,9 @@ fn parse_simple_statement(line: &SourceLine) -> Result<Statement> {
         });
     }
     let tokens = split_words(&line.text, line.number)?;
+    if let Some(statement) = parse_exec_write(&tokens, line.number)? {
+        return Ok(statement);
+    }
     if let Some(statement) = parse_env_exec(&tokens, line.number)? {
         return Ok(statement);
     }
@@ -243,6 +247,7 @@ fn parse_simple_statement(line: &SourceLine) -> Result<Statement> {
     let Some((command, args)) = tokens.split_first() else {
         bail!("{}: expected statement", line.number);
     };
+    validate_shell_command(command, args, line.number)?;
     match command.as_str() {
         "printf" => parse_printf(args, line.number),
         "eval" => bail!("{}: unsupported statement: eval", line.number),
@@ -323,6 +328,7 @@ fn parse_env_exec(tokens: &[String], line: usize) -> Result<Option<Statement>> {
     let Some(command) = argv_tokens.first() else {
         return Ok(None);
     };
+    validate_shell_command(command, &argv_tokens[1..], line)?;
     if !is_safe_command_name(command) {
         bail!("{line}: unsupported statement: {}", tokens.join(" "));
     }
@@ -342,23 +348,15 @@ fn parse_printf(args: &[String], line: usize) -> Result<Statement> {
                 value: parse_value_text(value, line)?,
             })
         }
-        _ => bail!("{line}: unsupported printf form"),
-    }
-}
-
-fn validate_external_tokens(tokens: &[String], line: usize) -> Result<()> {
-    for token in tokens {
-        if token.starts_with('"') || token.starts_with('\'') {
-            continue;
-        }
-        if token
-            .chars()
-            .any(|ch| matches!(ch, '|' | '>' | '<' | '&' | ';' | '`'))
+        [format, value, redirect, target]
+            if format == "'%s\\n'" && redirect == ">" && target == "&2" =>
         {
-            bail!("{line}: unsupported shell metacharacter in token: {token}");
+            Ok(Statement::Error {
+                value: parse_value_text(value, line)?,
+            })
         }
+        _ => bail!("{line}: unsupported printf form"),
     }
-    Ok(())
 }
 
 pub(super) fn option_to_name(option: &str, line: usize) -> Result<String> {
@@ -406,6 +404,7 @@ fn parse_predicate(text: &str, line: usize) -> Result<Predicate> {
     let Some(command) = tokens.first() else {
         bail!("{line}: command predicate cannot be empty");
     };
+    validate_shell_command(command, &tokens[1..], line)?;
     if !is_safe_command_name(command) {
         bail!("{line}: unsupported predicate: {text}");
     }
@@ -415,7 +414,7 @@ fn parse_predicate(text: &str, line: usize) -> Result<Predicate> {
     })
 }
 
-fn parse_values(tokens: &[String], line: usize) -> Result<Vec<Value>> {
+pub(super) fn parse_values(tokens: &[String], line: usize) -> Result<Vec<Value>> {
     tokens
         .iter()
         .map(|arg| parse_value_text(arg, line))
diff --git a/app/src/core/transpile/parse_argv.rs b/app/src/core/transpile/parse_argv.rs
index ca2f90f..dd823a4 100644
--- a/app/src/core/transpile/parse_argv.rs
+++ b/app/src/core/transpile/parse_argv.rs
@@ -2,7 +2,7 @@ use std::collections::BTreeMap;
 
 use anyhow::{Result, bail};
 
-use super::ast::{ArgvKind, ArgvSpec, Statement};
+use super::ast::{ArgvKind, ArgvPositional, ArgvSpec, Statement};
 use super::parse::{Parser, option_to_name};
 use super::parse_lex::assignment;
 
@@ -28,6 +28,7 @@ pub(super) fn parse_argv_block(parser: &mut Parser) -> Result<Statement> {
     parser.expect_exact("case \"$1\" in")?;
 
     let mut kinds = BTreeMap::new();
+    let mut positional = None;
     loop {
         let Some(line) = parser.peek().cloned() else {
             bail!("missing esac for argv parser");
@@ -42,6 +43,9 @@ pub(super) fn parse_argv_block(parser: &mut Parser) -> Result<Statement> {
             "*) fail \"unknown option: $1\" ;;" | "*) seal_fail \"unknown option: $1\" ;;" => {
                 parser.next();
             }
+            "*)" => {
+                positional = Some(parse_positional_arm(parser, &defaults)?);
+            }
             text if text.starts_with("--") && text.ends_with("=*)") => {
                 parse_eq_arm(parser, &mut kinds, text, line.number)?;
             }
@@ -57,7 +61,8 @@ pub(super) fn parse_argv_block(parser: &mut Parser) -> Result<Statement> {
     }
     parser.expect_exact("done")?;
     Ok(Statement::ArgvParse {
-        specs: argv_specs(order, defaults, kinds)?,
+        specs: argv_specs(order, defaults, kinds, positional.as_ref())?,
+        positional,
     })
 }
 
@@ -86,11 +91,7 @@ fn parse_option_arm(
     let option = text.trim_end_matches(')');
     let name = option_to_name(option, line)?;
     parser.next();
-    if parser
-        .peek_text()
-        .is_some_and(|text| text.starts_with("if [ \"$#\" -lt 2 ]; then "))
-    {
-        parser.next();
+    if parse_missing_value_guard(parser)? {
         parser.expect_exact(&format!("{name}=$2"))?;
         parser.expect_exact("shift 2")?;
         parser.expect_exact(";;")?;
@@ -104,6 +105,28 @@ fn parse_option_arm(
     Ok(())
 }
 
+fn parse_missing_value_guard(parser: &mut Parser) -> Result<bool> {
+    let Some(line) = parser.peek().cloned() else {
+        bail!("missing argv option arm body");
+    };
+    if line.text.starts_with("if [ \"$#\" -lt 2 ]; then ") {
+        parser.next();
+        return Ok(true);
+    }
+    if line.text != "if [ \"$#\" -lt 2 ]; then" {
+        return Ok(false);
+    }
+
+    parser.next();
+    while let Some(next) = parser.peek().cloned() {
+        parser.next();
+        if next.text == "fi" {
+            return Ok(true);
+        }
+    }
+    bail!("missing fi for argv missing-value guard");
+}
+
 fn parse_double_dash(parser: &mut Parser) -> Result<()> {
     parser.expect_exact("--)")?;
     parser.expect_exact("shift")?;
@@ -118,13 +141,61 @@ fn parse_help(parser: &mut Parser) -> Result<()> {
     parser.expect_exact(";;")
 }
 
+fn parse_positional_arm(
+    parser: &mut Parser,
+    defaults: &BTreeMap<String, String>,
+) -> Result<ArgvPositional> {
+    parser.expect_exact("*)")?;
+    let line = parser
+        .next()
+        .ok_or_else(|| anyhow::anyhow!("missing positional argv arm body"))?;
+    let Some(name) = line
+        .text
+        .strip_prefix("if [ -z \"$")
+        .and_then(|text| text.strip_suffix("\" ]; then"))
+    else {
+        bail!("{}: unsupported argv positional arm", line.number);
+    };
+    parser.expect_exact(&format!("{name}=$1"))?;
+    parser.expect_exact("shift")?;
+    parser.expect_exact("else")?;
+    let fail_line = parser
+        .next()
+        .ok_or_else(|| anyhow::anyhow!("missing argv positional else body"))?;
+    let extra_error = fail_line
+        .text
+        .strip_prefix("fail \"")
+        .and_then(|text| text.strip_suffix('"'))
+        .or_else(|| {
+            fail_line
+                .text
+                .strip_prefix("seal_fail \"")
+                .and_then(|text| text.strip_suffix('"'))
+        })
+        .ok_or_else(|| {
+            anyhow::anyhow!("{}: unsupported argv positional else arm", fail_line.number)
+        })?;
+    parser.expect_exact("fi")?;
+    parser.expect_exact(";;")?;
+    Ok(ArgvPositional {
+        name: name.to_string(),
+        default: defaults.get(name).cloned().unwrap_or_default(),
+        extra_error: extra_error.to_string(),
+    })
+}
+
 fn argv_specs(
     order: Vec<String>,
     mut defaults: BTreeMap<String, String>,
     mut kinds: BTreeMap<String, ArgvKind>,
+    positional: Option<&ArgvPositional>,
 ) -> Result<Vec<ArgvSpec>> {
     let mut specs = Vec::new();
     for name in order {
+        if positional.is_some_and(|positional| positional.name == name) {
+            defaults.remove(&name);
+            continue;
+        }
         let Some(kind) = kinds.remove(&name) else {
             bail!("missing argv parser arm for {name}");
         };
diff --git a/app/src/core/transpile/parse_command.rs b/app/src/core/transpile/parse_command.rs
new file mode 100644
index 0000000..7e1d628
--- /dev/null
+++ b/app/src/core/transpile/parse_command.rs
@@ -0,0 +1,100 @@
+use anyhow::{Result, bail};
+
+use super::ast::{OutputStream, Statement};
+use super::parse::parse_values;
+use super::parse_lex::is_safe_command_name;
+use super::value::parse_value_text;
+
+pub(super) fn parse_exec_write(tokens: &[String], line: usize) -> Result<Option<Statement>> {
+    let redirects = tokens
+        .iter()
+        .enumerate()
+        .filter(|(_, token)| matches!(token.as_str(), ">" | ">>" | "2>" | "2>>" | "|"))
+        .collect::<Vec<_>>();
+    if redirects.is_empty() {
+        return Ok(None);
+    }
+    if redirects.iter().any(|(_, token)| token.as_str() == "|") {
+        bail!("{line}: unsupported shell metacharacter: |");
+    }
+    if redirects.len() != 1 {
+        bail!("{line}: unsupported redirect combination");
+    }
+    let (index, token) = redirects[0];
+    if index == 0 || index + 2 != tokens.len() {
+        bail!("{line}: redirect requires one command and one file target");
+    }
+    let argv_tokens = &tokens[..index];
+    validate_external_tokens(argv_tokens, line)?;
+    let Some((command, args)) = argv_tokens.split_first() else {
+        bail!("{line}: redirect requires one command");
+    };
+    if command == "printf" && token.as_str() == ">" && tokens[index + 1] == "&2" {
+        return Ok(None);
+    }
+    validate_shell_command(command, args, line)?;
+    if !is_safe_command_name(command) {
+        bail!("{line}: unsupported statement: {}", tokens.join(" "));
+    }
+    if matches!(tokens[index + 1].as_str(), "&1" | "&2") {
+        bail!("{line}: unsupported redirect combination");
+    }
+    let path = parse_value_text(&tokens[index + 1], line)?;
+    let (stream, append) = match token.as_str() {
+        ">" => (OutputStream::Stdout, false),
+        ">>" => (OutputStream::Stdout, true),
+        "2>" => (OutputStream::Stderr, false),
+        "2>>" => (OutputStream::Stderr, true),
+        _ => unreachable!(),
+    };
+    Ok(Some(Statement::ExecWrite {
+        stream,
+        path,
+        append,
+        argv: parse_values(argv_tokens, line)?,
+    }))
+}
+
+pub(super) fn validate_external_tokens(tokens: &[String], line: usize) -> Result<()> {
+    for token in tokens {
+        if matches!(token.as_str(), ">" | ">>" | "2>" | "2>>" | "|") {
+            bail!("{line}: unsupported shell metacharacter: {token}");
+        }
+        if token.starts_with('"') || token.starts_with('\'') {
+            continue;
+        }
+        if token
+            .chars()
+            .any(|ch| matches!(ch, '|' | '>' | '<' | '&' | ';' | '`'))
+        {
+            bail!("{line}: unsupported shell metacharacter in token: {token}");
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn validate_shell_command(command: &str, args: &[String], line: usize) -> Result<()> {
+    if SHELL_ONLY_COMMANDS.contains(&command) {
+        bail!(
+            "{line}: shell-specific construct is not supported in .seal: {command}; use .sh/.ps1 or file an issue for first-class support"
+        );
+    }
+    let shell_launch = matches!(
+        (command, args.first().map(String::as_str)),
+        ("sh", Some("-c"))
+            | ("bash", Some("-c"))
+            | ("pwsh", Some("-Command" | "-command"))
+            | ("powershell", Some("-Command" | "-command"))
+    );
+    if shell_launch {
+        bail!(
+            "{line}: shell-specific construct is not supported in .seal: {command} {}; use .sh/.ps1 or file an issue for first-class support",
+            args.first().expect("checked first arg exists")
+        );
+    }
+    Ok(())
+}
+
+const SHELL_ONLY_COMMANDS: &[&str] = &[
+    ".", "alias", "exec", "export", "local", "readonly", "source", "trap", "unalias", "unset",
+];
diff --git a/app/src/core/transpile/parse_lex.rs b/app/src/core/transpile/parse_lex.rs
index 89ada12..988b091 100644
--- a/app/src/core/transpile/parse_lex.rs
+++ b/app/src/core/transpile/parse_lex.rs
@@ -9,7 +9,15 @@ pub(super) fn split_words(text: &str, line: usize) -> Result<Vec<String>> {
     let mut words = Vec::new();
     let mut current = String::new();
     let mut quote = None;
-    for ch in text.chars() {
+    let mut parameter_depth = 0_usize;
+    let mut chars = text.chars().peekable();
+    while let Some(ch) = chars.next() {
+        if quote.is_none() && ch == '$' && chars.peek() == Some(&'{') {
+            current.push(ch);
+            current.push(chars.next().expect("peeked char should exist"));
+            parameter_depth += 1;
+            continue;
+        }
         match quote {
             Some(q) if ch == q => {
                 current.push(ch);
@@ -20,7 +28,40 @@ pub(super) fn split_words(text: &str, line: usize) -> Result<Vec<String>> {
                 current.push(ch);
                 quote = Some(ch);
             }
-            None if ch.is_whitespace() => {
+            None if ch == '}' && parameter_depth > 0 => {
+                current.push(ch);
+                parameter_depth -= 1;
+            }
+            None if ch == '2' && matches!(chars.peek(), Some('>')) => {
+                if !current.is_empty() {
+                    words.push(std::mem::take(&mut current));
+                }
+                chars.next();
+                if matches!(chars.peek(), Some('>')) {
+                    chars.next();
+                    words.push("2>>".to_string());
+                } else {
+                    words.push("2>".to_string());
+                }
+            }
+            None if ch == '>' => {
+                if !current.is_empty() {
+                    words.push(std::mem::take(&mut current));
+                }
+                if matches!(chars.peek(), Some('>')) {
+                    chars.next();
+                    words.push(">>".to_string());
+                } else {
+                    words.push(">".to_string());
+                }
+            }
+            None if ch == '|' => {
+                if !current.is_empty() {
+                    words.push(std::mem::take(&mut current));
+                }
+                words.push("|".to_string());
+            }
+            None if ch.is_whitespace() && parameter_depth == 0 => {
                 if !current.is_empty() {
                     words.push(std::mem::take(&mut current));
                 }
@@ -31,6 +72,9 @@ pub(super) fn split_words(text: &str, line: usize) -> Result<Vec<String>> {
     if let Some(q) = quote {
         bail!("{line}: unterminated {q} quote");
     }
+    if parameter_depth != 0 {
+        bail!("{line}: unterminated parameter expansion");
+    }
     if !current.is_empty() {
         words.push(current);
     }
@@ -42,8 +86,15 @@ pub(super) fn split_test_words(text: &str, line: usize) -> Result<Vec<String>> {
     let mut current = String::new();
     let mut quote = None;
     let mut command_depth = 0_usize;
+    let mut parameter_depth = 0_usize;
     let mut chars = text.chars().peekable();
     while let Some(ch) = chars.next() {
+        if quote.is_none() && ch == '$' && chars.peek() == Some(&'{') {
+            current.push(ch);
+            current.push(chars.next().expect("peeked char should exist"));
+            parameter_depth += 1;
+            continue;
+        }
         if ch == '$' && chars.peek() == Some(&'(') {
             current.push(ch);
             current.push(chars.next().expect("peeked char should exist"));
@@ -66,7 +117,11 @@ pub(super) fn split_test_words(text: &str, line: usize) -> Result<Vec<String>> {
                 current.push(ch);
                 quote = Some(ch);
             }
-            None if ch.is_whitespace() => {
+            None if ch == '}' && parameter_depth > 0 => {
+                current.push(ch);
+                parameter_depth -= 1;
+            }
+            None if ch.is_whitespace() && parameter_depth == 0 => {
                 if !current.is_empty() {
                     words.push(std::mem::take(&mut current));
                 }
@@ -80,6 +135,9 @@ pub(super) fn split_test_words(text: &str, line: usize) -> Result<Vec<String>> {
     if command_depth != 0 {
         bail!("{line}: unterminated command substitution");
     }
+    if parameter_depth != 0 {
+        bail!("{line}: unterminated parameter expansion");
+    }
     if !current.is_empty() {
         words.push(current);
     }
diff --git a/app/src/core/transpile/runner/args.rs b/app/src/core/transpile/runner/args.rs
new file mode 100644
index 0000000..5a1d3ab
--- /dev/null
+++ b/app/src/core/transpile/runner/args.rs
@@ -0,0 +1,163 @@
+use anyhow::{Result, bail};
+
+use super::*;
+
+impl<'a> Runner<'a> {
+    pub(super) fn parse_argv(
+        &mut self,
+        specs: &[ArgvSpec],
+        positional: Option<&ArgvPositional>,
+    ) -> Result<()> {
+        let argv = self
+            .vars
+            .get("__seal_argv")
+            .map(|value| split_words(value))
+            .unwrap_or_default();
+        self.vars
+            .insert("__seal_argc".to_string(), argv.len().to_string());
+        self.vars
+            .insert("__seal_help".to_string(), "false".to_string());
+        for spec in specs {
+            let value = match spec.kind {
+                ArgvKind::String => spec.default.clone().unwrap_or_default(),
+                ArgvKind::Flag => "false".to_string(),
+            };
+            self.vars.insert(spec.name.clone(), value);
+        }
+        if let Some(positional) = positional {
+            self.vars
+                .insert(positional.name.clone(), positional.default.clone());
+        }
+        let mut index = 0;
+        while index < argv.len() {
+            let arg = &argv[index];
+            if arg == "--" {
+                break;
+            }
+            if matches!(arg.as_str(), "-h" | "--help" | "help") {
+                self.vars
+                    .insert("__seal_help".to_string(), "true".to_string());
+                index += 1;
+                continue;
+            }
+            let Some(spec) = find_spec(specs, arg) else {
+                if let Some(positional) = positional {
+                    let current = self.vars.get(&positional.name).cloned().unwrap_or_default();
+                    if current.is_empty() {
+                        self.vars.insert(positional.name.clone(), arg.clone());
+                        index += 1;
+                        continue;
+                    }
+                    eprintln!("{}", positional.extra_error.replace("$1", arg));
+                    bail!("argv parse failed");
+                }
+                eprintln!("unknown option: {arg}");
+                bail!("argv parse failed");
+            };
+            match spec.kind {
+                ArgvKind::Flag => {
+                    self.vars.insert(spec.name.clone(), "true".to_string());
+                    index += 1;
+                }
+                ArgvKind::String => {
+                    let option = option_name(&spec.name);
+                    if let Some(value) = arg.strip_prefix(&(option.clone() + "=")) {
+                        self.vars.insert(spec.name.clone(), value.to_string());
+                        index += 1;
+                    } else {
+                        let Some(value) = argv.get(index + 1) else {
+                            eprintln!("missing value for {option}");
+                            bail!("argv parse failed");
+                        };
+                        self.vars.insert(spec.name.clone(), value.clone());
+                        index += 2;
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn set_function_args(&mut self, argv: &[Value]) -> Result<ArgSnapshot> {
+        let values = self.expanded_values(argv)?;
+        let old_len = self.argc();
+        let old = (0..=old_len)
+            .map(|index| self.vars.remove(&index.to_string()))
+            .collect::<Vec<_>>();
+        let snapshot = ArgSnapshot {
+            argv: self.vars.remove("__seal_argv"),
+            values: old,
+        };
+        self.set_positional_args(&values);
+        Ok(snapshot)
+    }
+
+    pub(super) fn restore_function_args(&mut self, old: ArgSnapshot) {
+        let current_len = self.argc();
+        for index in 0..=current_len {
+            self.vars.remove(&index.to_string());
+        }
+        for (index, value) in old.values.into_iter().enumerate() {
+            match value {
+                Some(value) => {
+                    self.vars.insert(index.to_string(), value);
+                }
+                None => {
+                    self.vars.remove(&index.to_string());
+                }
+            }
+        }
+        match old.argv {
+            Some(value) => {
+                self.vars.insert("__seal_argv".to_string(), value);
+            }
+            None => {
+                self.vars.remove("__seal_argv");
+            }
+        }
+    }
+
+    pub(super) fn expanded_values(&self, values: &[Value]) -> Result<Vec<String>> {
+        let mut expanded = Vec::new();
+        for value in values {
+            match value {
+                Value::Args => expanded.extend(self.current_args()),
+                Value::Argc => expanded.push(self.argc().to_string()),
+                _ => expanded.push(self.try_value(value)?),
+            }
+        }
+        Ok(expanded)
+    }
+
+    pub(super) fn argc(&self) -> usize {
+        self.vars
+            .get("0")
+            .and_then(|value| value.parse::<usize>().ok())
+            .unwrap_or_default()
+    }
+
+    pub(super) fn current_args(&self) -> Vec<String> {
+        (1..=self.argc())
+            .filter_map(|index| self.vars.get(&index.to_string()).cloned())
+            .collect()
+    }
+
+    pub(super) fn shift_args(&mut self, count: usize) {
+        let args = self.current_args();
+        let remaining = args.into_iter().skip(count).collect::<Vec<_>>();
+        self.set_positional_args(&remaining);
+    }
+
+    fn set_positional_args(&mut self, values: &[String]) {
+        let old_len = self.argc();
+        for index in 0..=old_len {
+            self.vars.remove(&index.to_string());
+        }
+        for (index, value) in values.iter().enumerate() {
+            self.vars.insert((index + 1).to_string(), value.clone());
+        }
+        self.vars.insert("0".to_string(), values.len().to_string());
+        self.vars
+            .insert("__seal_argv".to_string(), shell_words(values));
+    }
+}
diff --git a/app/src/core/transpile/runner.rs b/app/src/core/transpile/runner/mod.rs
similarity index 52%
rename from app/src/core/transpile/runner.rs
rename to app/src/core/transpile/runner/mod.rs
index 72cbe64..53f5341 100644
--- a/app/src/core/transpile/runner.rs
+++ b/app/src/core/transpile/runner/mod.rs
@@ -1,17 +1,23 @@
-use std::{
-    collections::BTreeMap,
-    path::Path,
-    process::{Command, Stdio},
-    time::Duration,
-};
+use std::{collections::BTreeMap, path::Path, process::Command, time::Duration};
 
 use anyhow::{Context, Result, bail};
 
 use crate::core::tool;
 
-use super::ast::{ArgvKind, ArgvSpec, Item, Predicate, Program, Statement, Value};
+use self::support::{
+    ArgSnapshot, CaptureMode, CommandOutput, SourceState, case_matches, find_spec,
+    map_source_state, option_name, shell_words, split_words, write_stderr, write_stderr_line,
+    write_stdout, write_stdout_line, write_stream_file,
+};
+use super::ast::{
+    ArgvKind, ArgvPositional, ArgvSpec, ExpansionOp, Item, Predicate, Program, Statement, Value,
+    ValueSource,
+};
 use super::parse::parse_seal;
 
+mod args;
+mod support;
+
 pub(crate) fn run_seal_file(
     path: &Path,
     argv: &[String],
@@ -28,6 +34,7 @@ struct Runner<'a> {
     program: &'a Program,
     vars: BTreeMap<String, String>,
     env: BTreeMap<String, String>,
+    stdout_stack: Vec<String>,
 }
 
 enum Flow {
@@ -36,11 +43,6 @@ enum Flow {
     Exit(i32),
 }
 
-struct ArgSnapshot {
-    argv: Option<String>,
-    values: Vec<Option<String>>,
-}
-
 impl<'a> Runner<'a> {
     fn new(program: &'a Program, argv: &[String], env_overlay: &[(String, String)]) -> Self {
         let mut env = std::env::vars().collect::<BTreeMap<_, _>>();
@@ -51,7 +53,12 @@ impl<'a> Runner<'a> {
         for (index, value) in argv.iter().enumerate() {
             vars.insert((index + 1).to_string(), value.clone());
         }
-        Self { program, vars, env }
+        Self {
+            program,
+            vars,
+            env,
+            stdout_stack: Vec::new(),
+        }
     }
 
     fn run_program(&mut self) -> Result<i32> {
@@ -88,10 +95,12 @@ impl<'a> Runner<'a> {
     fn run_statement(&mut self, statement: &Statement) -> Result<Flow> {
         match statement {
             Statement::Assign { name, value } => {
-                let value = self.value(value);
+                let value = self.try_value(value)?;
                 self.vars.insert(name.clone(), value);
             }
-            Statement::ArgvParse { specs } => self.parse_argv(specs)?,
+            Statement::ArgvParse { specs, positional } => {
+                self.parse_argv(specs, positional.as_ref())?
+            }
             Statement::Shift { count } => self.shift_args(*count),
             Statement::ExecChecked { argv } => {
                 let code = self.run_external(argv, CaptureMode::None)?.code;
@@ -99,11 +108,24 @@ impl<'a> Runner<'a> {
                     return Ok(Flow::Exit(code));
                 }
             }
+            Statement::ExecWrite {
+                stream,
+                path,
+                append,
+                argv,
+            } => {
+                let output = self.run_external(argv, CaptureMode::All)?;
+                let path = self.try_value(path)?;
+                write_stream_file(stream, Path::new(&path), *append, &output)?;
+                if output.code != 0 {
+                    return Ok(Flow::Exit(output.code));
+                }
+            }
             Statement::EnvExecChecked { env, argv } => {
                 let overlay = env
                     .iter()
-                    .map(|item| (item.name.clone(), self.value(&item.value)))
-                    .collect::<Vec<_>>();
+                    .map(|item| Ok((item.name.clone(), self.try_value(&item.value)?)))
+                    .collect::<Result<Vec<_>>>()?;
                 let code = self
                     .run_external_with_env(argv, CaptureMode::None, &overlay)?
                     .code;
@@ -119,6 +141,24 @@ impl<'a> Runner<'a> {
                 self.vars
                     .insert(name.clone(), output.stdout.trim().to_string());
             }
+            Statement::CaptureFunction {
+                name,
+                function,
+                argv,
+            } => {
+                let old_args = self.set_function_args(argv)?;
+                self.stdout_stack.push(String::new());
+                let flow = self.run_function(function)?;
+                let captured = self
+                    .stdout_stack
+                    .pop()
+                    .expect("stdout capture stack should be balanced");
+                self.restore_function_args(old_args);
+                if !matches!(flow, Flow::Continue) {
+                    return Ok(flow);
+                }
+                self.vars.insert(name.clone(), captured.trim().to_string());
+            }
             Statement::If {
                 predicate,
                 then_body,
@@ -143,7 +183,7 @@ impl<'a> Runner<'a> {
                 }
             }
             Statement::Case { value, arms } => {
-                let value = self.value(value);
+                let value = self.try_value(value)?;
                 for arm in arms {
                     if arm
                         .patterns
@@ -159,17 +199,20 @@ impl<'a> Runner<'a> {
                 }
             }
             Statement::CallFunction { name, argv } => {
-                let old_args = self.set_function_args(argv);
+                let old_args = self.set_function_args(argv)?;
                 let flow = self.run_function(name)?;
                 self.restore_function_args(old_args);
                 if !matches!(flow, Flow::Continue) {
                     return Ok(flow);
                 }
             }
-            Statement::Print { value } => println!("{}", self.value(value)),
-            Statement::Error { value } => eprintln!("{}", self.value(value)),
+            Statement::Print { value } => {
+                let text = self.try_value(value)?;
+                write_stdout_line(&mut self.stdout_stack, &text)?
+            }
+            Statement::Error { value } => write_stderr_line(&self.try_value(value)?)?,
             Statement::Fail { value } => {
-                eprintln!("{}", self.value(value));
+                write_stderr_line(&self.try_value(value)?)?;
                 return Ok(Flow::Exit(1));
             }
             Statement::Exit { code } => return Ok(Flow::Exit(*code)),
@@ -192,87 +235,29 @@ impl<'a> Runner<'a> {
         self.run_body(body)
     }
 
-    fn parse_argv(&mut self, specs: &[ArgvSpec]) -> Result<()> {
-        let argv = self
-            .vars
-            .get("__seal_argv")
-            .map(|value| split_words(value))
-            .unwrap_or_default();
-        self.vars
-            .insert("__seal_argc".to_string(), argv.len().to_string());
-        self.vars
-            .insert("__seal_help".to_string(), "false".to_string());
-        for spec in specs {
-            let value = match spec.kind {
-                ArgvKind::String => spec.default.clone().unwrap_or_default(),
-                ArgvKind::Flag => "false".to_string(),
-            };
-            self.vars.insert(spec.name.clone(), value);
-        }
-        let mut index = 0;
-        while index < argv.len() {
-            let arg = &argv[index];
-            if arg == "--" {
-                break;
-            }
-            if matches!(arg.as_str(), "-h" | "--help" | "help") {
-                self.vars
-                    .insert("__seal_help".to_string(), "true".to_string());
-                index += 1;
-                continue;
-            }
-            let Some(spec) = find_spec(specs, arg) else {
-                eprintln!("unknown option: {arg}");
-                bail!("argv parse failed");
-            };
-            match spec.kind {
-                ArgvKind::Flag => {
-                    self.vars.insert(spec.name.clone(), "true".to_string());
-                    index += 1;
-                }
-                ArgvKind::String => {
-                    let option = option_name(&spec.name);
-                    if let Some(value) = arg.strip_prefix(&(option.clone() + "=")) {
-                        self.vars.insert(spec.name.clone(), value.to_string());
-                        index += 1;
-                    } else {
-                        let Some(value) = argv.get(index + 1) else {
-                            eprintln!("missing value for {option}");
-                            bail!("argv parse failed");
-                        };
-                        self.vars.insert(spec.name.clone(), value.clone());
-                        index += 2;
-                    }
-                }
-            }
-        }
-        Ok(())
-    }
-
-    fn value(&self, value: &Value) -> String {
-        match value {
+    fn try_value(&self, value: &Value) -> Result<String> {
+        Ok(match value {
             Value::Literal { text } => text.clone(),
             Value::Argc => self.argc().to_string(),
-            Value::Var { name } => self.vars.get(name).cloned().unwrap_or_default(),
             Value::Args => shell_words(&self.current_args()),
-            Value::Env { name } => self.env.get(name).cloned().unwrap_or_default(),
-            Value::EnvDefault { name, default } => self
-                .env
-                .get(name)
-                .filter(|value| !value.is_empty())
-                .cloned()
-                .unwrap_or_else(|| default.clone()),
-            Value::Concat { parts } => parts.iter().map(|part| self.value(part)).collect(),
-        }
+            Value::Expand { source, op } => self.expand_value(source, op)?,
+            Value::Concat { parts } => {
+                let mut combined = String::new();
+                for part in parts {
+                    combined.push_str(&self.try_value(part)?);
+                }
+                combined
+            }
+        })
     }
 
-    fn predicate(&self, predicate: &Predicate) -> Result<bool> {
+    fn predicate(&mut self, predicate: &Predicate) -> Result<bool> {
         Ok(match predicate {
             Predicate::Command { argv } => self.run_external(argv, CaptureMode::None)?.code == 0,
-            Predicate::Empty { value } => self.value(value).is_empty(),
-            Predicate::NotEmpty { value } => !self.value(value).is_empty(),
-            Predicate::Eq { left, right } => self.value(left) == self.value(right),
-            Predicate::Neq { left, right } => self.value(left) != self.value(right),
+            Predicate::Empty { value } => self.try_value(value)?.is_empty(),
+            Predicate::NotEmpty { value } => !self.try_value(value)?.is_empty(),
+            Predicate::Eq { left, right } => self.try_value(left)? == self.try_value(right)?,
+            Predicate::Neq { left, right } => self.try_value(left)? != self.try_value(right)?,
             Predicate::IntLt { left, right } => self.int_value(left)? < self.int_value(right)?,
             Predicate::IntLte { left, right } => self.int_value(left)? <= self.int_value(right)?,
             Predicate::IntGt { left, right } => self.int_value(left)? > self.int_value(right)?,
@@ -283,178 +268,90 @@ impl<'a> Runner<'a> {
             Predicate::JsonNotEmpty { value } => {
                 self.tool_path(&["json", "empty"], std::slice::from_ref(value))? == "false"
             }
-            Predicate::FileExists { path } => Path::new(&self.value(path)).is_file(),
-            Predicate::DirExists { path } => Path::new(&self.value(path)).is_dir(),
+            Predicate::FileExists { path } => Path::new(&self.try_value(path)?).is_file(),
+            Predicate::DirExists { path } => Path::new(&self.try_value(path)?).is_dir(),
         })
     }
 
     fn int_value(&self, value: &Value) -> Result<i64> {
-        let value = self.value(value);
+        let value = self.try_value(value)?;
         value
             .parse::<i64>()
             .with_context(|| format!("invalid integer: {value}"))
     }
 
+    fn expand_value(&self, source: &ValueSource, op: &ExpansionOp) -> Result<String> {
+        let state = self.source_state(source);
+        match op {
+            ExpansionOp::Plain => Ok(match state {
+                SourceState::Unset => String::new(),
+                SourceState::Empty => String::new(),
+                SourceState::Present(value) => value,
+            }),
+            ExpansionOp::DefaultIfUnsetOrEmpty { fallback } => Ok(match state {
+                SourceState::Present(value) => value,
+                SourceState::Unset | SourceState::Empty => fallback.clone(),
+            }),
+            ExpansionOp::RequireNonEmpty { message } => match state {
+                SourceState::Present(value) => Ok(value),
+                SourceState::Unset | SourceState::Empty => bail!("{message}"),
+            },
+        }
+    }
+
+    fn source_state(&self, source: &ValueSource) -> SourceState {
+        match source {
+            ValueSource::Env { name } => map_source_state(self.env.get(name).cloned()),
+            ValueSource::Var { name } => map_source_state(self.vars.get(name).cloned()),
+        }
+    }
+
     fn tool_path(&self, path: &[&str], argv: &[Value]) -> Result<String> {
         let mut args = path.iter().map(|part| part.to_string()).collect::<Vec<_>>();
-        args.extend(self.expanded_values(argv));
+        args.extend(self.expanded_values(argv)?);
         Ok(tool::eval(&args)?.unwrap_or_default())
     }
 
-    fn run_external(&self, argv: &[Value], capture: CaptureMode) -> Result<CommandOutput> {
+    fn run_external(&mut self, argv: &[Value], capture: CaptureMode) -> Result<CommandOutput> {
         self.run_external_with_env(argv, capture, &[])
     }
 
     fn run_external_with_env(
-        &self,
+        &mut self,
         argv: &[Value],
         capture: CaptureMode,
         env_overlay: &[(String, String)],
     ) -> Result<CommandOutput> {
-        let argv = self.expanded_values(argv);
+        let argv = self.expanded_values(argv)?;
         let Some((program, args)) = argv.split_first() else {
             bail!("external command cannot be empty");
         };
         let mut command = Command::new(program);
         command.args(args).envs(&self.env);
         command.envs(env_overlay.iter().map(|(key, value)| (key, value)));
-        if matches!(capture, CaptureMode::None) {
+        if matches!(capture, CaptureMode::None) && self.stdout_stack.is_empty() {
             let status = command
                 .status()
                 .with_context(|| format!("failed to execute command: {program}"))?;
             return Ok(CommandOutput {
                 code: status.code().unwrap_or(1),
                 stdout: String::new(),
+                stderr: String::new(),
             });
         }
-        command.stdout(Stdio::piped());
         let output = command
             .output()
             .with_context(|| format!("failed to execute command: {program}"))?;
         let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
+        let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+        if matches!(capture, CaptureMode::None) {
+            write_stdout(&mut self.stdout_stack, &stdout)?;
+            write_stderr(&stderr)?;
+        }
         Ok(CommandOutput {
             code: output.status.code().unwrap_or(1),
             stdout,
+            stderr,
         })
     }
-
-    fn set_function_args(&mut self, argv: &[Value]) -> ArgSnapshot {
-        let values = self.expanded_values(argv);
-        let old_len = self.argc();
-        let old = (0..=old_len)
-            .map(|index| self.vars.remove(&index.to_string()))
-            .collect::<Vec<_>>();
-        let snapshot = ArgSnapshot {
-            argv: self.vars.remove("__seal_argv"),
-            values: old,
-        };
-        self.set_positional_args(&values);
-        snapshot
-    }
-
-    fn restore_function_args(&mut self, old: ArgSnapshot) {
-        let current_len = self.argc();
-        for index in 0..=current_len {
-            self.vars.remove(&index.to_string());
-        }
-        for (index, value) in old.values.into_iter().enumerate() {
-            match value {
-                Some(value) => {
-                    self.vars.insert(index.to_string(), value);
-                }
-                None => {
-                    self.vars.remove(&index.to_string());
-                }
-            }
-        }
-        match old.argv {
-            Some(value) => {
-                self.vars.insert("__seal_argv".to_string(), value);
-            }
-            None => {
-                self.vars.remove("__seal_argv");
-            }
-        }
-    }
-
-    fn expanded_values(&self, values: &[Value]) -> Vec<String> {
-        let mut expanded = Vec::new();
-        for value in values {
-            match value {
-                Value::Args => expanded.extend(self.current_args()),
-                Value::Argc => expanded.push(self.argc().to_string()),
-                _ => expanded.push(self.value(value)),
-            }
-        }
-        expanded
-    }
-
-    fn argc(&self) -> usize {
-        self.vars
-            .get("0")
-            .and_then(|value| value.parse::<usize>().ok())
-            .unwrap_or_default()
-    }
-
-    fn current_args(&self) -> Vec<String> {
-        (1..=self.argc())
-            .filter_map(|index| self.vars.get(&index.to_string()).cloned())
-            .collect()
-    }
-
-    fn shift_args(&mut self, count: usize) {
-        let args = self.current_args();
-        let remaining = args.into_iter().skip(count).collect::<Vec<_>>();
-        self.set_positional_args(&remaining);
-    }
-
-    fn set_positional_args(&mut self, values: &[String]) {
-        let old_len = self.argc();
-        for index in 0..=old_len {
-            self.vars.remove(&index.to_string());
-        }
-        for (index, value) in values.iter().enumerate() {
-            self.vars.insert((index + 1).to_string(), value.clone());
-        }
-        self.vars.insert("0".to_string(), values.len().to_string());
-        self.vars
-            .insert("__seal_argv".to_string(), shell_words(values));
-    }
-}
-
-enum CaptureMode {
-    None,
-    Stdout,
-}
-
-struct CommandOutput {
-    code: i32,
-    stdout: String,
-}
-
-fn find_spec<'a>(specs: &'a [ArgvSpec], arg: &str) -> Option<&'a ArgvSpec> {
-    specs.iter().find(|spec| {
-        let option = option_name(&spec.name);
-        arg == option || arg.starts_with(&(option + "="))
-    })
-}
-
-fn option_name(name: &str) -> String {
-    format!("--{}", name.replace('_', "-"))
-}
-
-fn case_matches(pattern: &str, value: &str) -> bool {
-    pattern == "*" || pattern == value
-}
-
-fn shell_words(argv: &[String]) -> String {
-    argv.join("\u{1f}")
-}
-
-fn split_words(value: &str) -> Vec<String> {
-    if value.is_empty() {
-        Vec::new()
-    } else {
-        value.split('\u{1f}').map(str::to_string).collect()
-    }
 }
diff --git a/app/src/core/transpile/runner/support.rs b/app/src/core/transpile/runner/support.rs
new file mode 100644
index 0000000..6bfa3e6
--- /dev/null
+++ b/app/src/core/transpile/runner/support.rs
@@ -0,0 +1,146 @@
+use std::path::Path;
+
+use anyhow::{Context, Result};
+
+use super::super::ast::{ArgvSpec, OutputStream};
+
+pub(super) enum CaptureMode {
+    None,
+    Stdout,
+    All,
+}
+
+pub(super) struct CommandOutput {
+    pub(super) code: i32,
+    pub(super) stdout: String,
+    pub(super) stderr: String,
+}
+
+pub(super) struct ArgSnapshot {
+    pub(super) argv: Option<String>,
+    pub(super) values: Vec<Option<String>>,
+}
+
+pub(super) enum SourceState {
+    Unset,
+    Empty,
+    Present(String),
+}
+
+pub(super) fn write_stream_file(
+    stream: &OutputStream,
+    path: &Path,
+    append: bool,
+    output: &CommandOutput,
+) -> Result<()> {
+    use std::io::Write;
+
+    if let Some(parent) = path.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        std::fs::create_dir_all(parent)
+            .with_context(|| format!("failed to create parent directory: {}", parent.display()))?;
+    }
+    let captured = match stream {
+        OutputStream::Stdout => output.stdout.as_bytes(),
+        OutputStream::Stderr => output.stderr.as_bytes(),
+    };
+    if append {
+        let mut file = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(path)
+            .with_context(|| format!("failed to append file: {}", path.display()))?;
+        file.write_all(captured)
+            .with_context(|| format!("failed to append file: {}", path.display()))?;
+    } else {
+        std::fs::write(path, captured)
+            .with_context(|| format!("failed to write file: {}", path.display()))?;
+    }
+    match stream {
+        OutputStream::Stdout => {
+            std::io::stderr()
+                .write_all(output.stderr.as_bytes())
+                .context("failed to write stderr")?;
+        }
+        OutputStream::Stderr => {
+            std::io::stdout()
+                .write_all(output.stdout.as_bytes())
+                .context("failed to write stdout")?;
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn find_spec<'a>(specs: &'a [ArgvSpec], arg: &str) -> Option<&'a ArgvSpec> {
+    specs.iter().find(|spec| {
+        let option = option_name(&spec.name);
+        arg == option || arg.starts_with(&(option + "="))
+    })
+}
+
+pub(super) fn option_name(name: &str) -> String {
+    format!("--{}", name.replace('_', "-"))
+}
+
+pub(super) fn case_matches(pattern: &str, value: &str) -> bool {
+    pattern == "*" || pattern == value
+}
+
+pub(super) fn shell_words(argv: &[String]) -> String {
+    argv.join("\u{1f}")
+}
+
+pub(super) fn split_words(value: &str) -> Vec<String> {
+    if value.is_empty() {
+        Vec::new()
+    } else {
+        value.split('\u{1f}').map(str::to_string).collect()
+    }
+}
+
+pub(super) fn map_source_state(value: Option<String>) -> SourceState {
+    match value {
+        None => SourceState::Unset,
+        Some(value) if value.is_empty() => SourceState::Empty,
+        Some(value) => SourceState::Present(value),
+    }
+}
+
+pub(super) fn write_stdout(stdout_stack: &mut [String], text: &str) -> Result<()> {
+    use std::io::Write;
+
+    if text.is_empty() {
+        return Ok(());
+    }
+    if let Some(buffer) = stdout_stack.last_mut() {
+        buffer.push_str(text);
+        return Ok(());
+    }
+    std::io::stdout()
+        .write_all(text.as_bytes())
+        .context("failed to write stdout")
+}
+
+pub(super) fn write_stdout_line(stdout_stack: &mut [String], text: &str) -> Result<()> {
+    let mut line = text.to_string();
+    line.push('\n');
+    write_stdout(stdout_stack, &line)
+}
+
+pub(super) fn write_stderr(text: &str) -> Result<()> {
+    use std::io::Write;
+
+    if text.is_empty() {
+        return Ok(());
+    }
+    std::io::stderr()
+        .write_all(text.as_bytes())
+        .context("failed to write stderr")
+}
+
+pub(super) fn write_stderr_line(text: &str) -> Result<()> {
+    let mut line = text.to_string();
+    line.push('\n');
+    write_stderr(&line)
+}
diff --git a/app/src/core/transpile/value.rs b/app/src/core/transpile/value.rs
index 2897a01..e7d5e1b 100644
--- a/app/src/core/transpile/value.rs
+++ b/app/src/core/transpile/value.rs
@@ -1,6 +1,6 @@
 use anyhow::{Result, bail};
 
-use super::ast::Value;
+use super::ast::{ExpansionOp, Value, ValueSource};
 
 pub(crate) fn parse_value_text(text: &str, line: usize) -> Result<Value> {
     if text == "$@" || text == "\"$@\"" {
@@ -25,29 +25,25 @@ pub(crate) fn parse_value_text(text: &str, line: usize) -> Result<Value> {
     }
     if let Some(name) = text.strip_prefix('$') {
         if is_positional_name(name) {
-            return Ok(Value::Var {
-                name: name.to_string(),
+            return Ok(Value::Expand {
+                source: ValueSource::Var {
+                    name: name.to_string(),
+                },
+                op: ExpansionOp::Plain,
             });
         }
         if let Some(name) = name
             .strip_prefix('{')
             .and_then(|name| name.strip_suffix('}'))
         {
-            if let Some((name, default)) = name.split_once(":-") {
-                validate_name(name, line)?;
-                return Ok(Value::EnvDefault {
-                    name: name.to_string(),
-                    default: default.to_string(),
-                });
-            }
-            validate_name(name, line)?;
-            return Ok(Value::Env {
-                name: name.to_string(),
-            });
+            return parse_braced_expansion(name, line);
         }
         validate_name(name, line)?;
-        return Ok(Value::Var {
-            name: name.to_string(),
+        return Ok(Value::Expand {
+            source: ValueSource::Var {
+                name: name.to_string(),
+            },
+            op: ExpansionOp::Plain,
         });
     }
     if text.contains('$') {
@@ -81,16 +77,7 @@ fn parse_template(text: &str, line: usize) -> Result<Value> {
                 }
                 inner.push(next);
             }
-            if let Some((name, default)) = inner.split_once(":-") {
-                validate_name(name, line)?;
-                parts.push(Value::EnvDefault {
-                    name: name.to_string(),
-                    default: default.to_string(),
-                });
-            } else {
-                validate_name(&inner, line)?;
-                parts.push(Value::Env { name: inner });
-            }
+            parts.push(parse_braced_expansion(&inner, line)?);
             continue;
         }
         let mut name = String::new();
@@ -104,7 +91,10 @@ fn parse_template(text: &str, line: usize) -> Result<Value> {
         {
             name.push(next);
             chars.next();
-            parts.push(Value::Var { name });
+            parts.push(Value::Expand {
+                source: ValueSource::Var { name },
+                op: ExpansionOp::Plain,
+            });
             continue;
         }
         while let Some(next) = chars.peek().copied() {
@@ -116,7 +106,10 @@ fn parse_template(text: &str, line: usize) -> Result<Value> {
             }
         }
         validate_name(&name, line)?;
-        parts.push(Value::Var { name });
+        parts.push(Value::Expand {
+            source: ValueSource::Var { name },
+            op: ExpansionOp::Plain,
+        });
     }
     if !literal.is_empty() {
         parts.push(Value::Literal { text: literal });
@@ -128,7 +121,45 @@ fn parse_template(text: &str, line: usize) -> Result<Value> {
 }
 
 fn is_positional_name(name: &str) -> bool {
-    name.len() == 1 && name.bytes().all(|byte| byte.is_ascii_digit())
+    !name.is_empty() && name.bytes().all(|byte| byte.is_ascii_digit())
+}
+
+fn parse_braced_expansion(text: &str, line: usize) -> Result<Value> {
+    if let Some((name, message)) = text.split_once(":?") {
+        let source = parse_braced_source(name, line)?;
+        return Ok(Value::Expand {
+            source,
+            op: ExpansionOp::RequireNonEmpty {
+                message: message.to_string(),
+            },
+        });
+    }
+    if let Some((name, fallback)) = text.split_once(":-") {
+        let source = parse_braced_source(name, line)?;
+        return Ok(Value::Expand {
+            source,
+            op: ExpansionOp::DefaultIfUnsetOrEmpty {
+                fallback: fallback.to_string(),
+            },
+        });
+    }
+    let source = parse_braced_source(text, line)?;
+    Ok(Value::Expand {
+        source,
+        op: ExpansionOp::Plain,
+    })
+}
+
+fn parse_braced_source(name: &str, line: usize) -> Result<ValueSource> {
+    if is_positional_name(name) {
+        return Ok(ValueSource::Var {
+            name: name.to_string(),
+        });
+    }
+    validate_name(name, line)?;
+    Ok(ValueSource::Env {
+        name: name.to_string(),
+    })
 }
 
 fn validate_name(name: &str, line: usize) -> Result<()> {
diff --git a/app/tests/discovery.rs b/app/tests/discovery.rs
index 543afac..27ae527 100644
--- a/app/tests/discovery.rs
+++ b/app/tests/discovery.rs
@@ -3,7 +3,10 @@ use std::process::Command;
 use tempfile::TempDir;
 
 fn bin() -> Command {
-    Command::new(env!("CARGO_BIN_EXE_runseal"))
+    let mut command = Command::new(env!("CARGO_BIN_EXE_runseal"));
+    command.env_remove("RUNSEAL_PROFILE_HOME");
+    command.env_remove("RUNSEAL_PROFILE_PATH");
+    command
 }
 
 #[cfg(unix)]
diff --git a/app/tests/fixtures/estate/kube.seal b/app/tests/fixtures/estate/kube.seal
index 4e91e9f..a326e3d 100644
--- a/app/tests/fixtures/estate/kube.seal
+++ b/app/tests/fixtures/estate/kube.seal
@@ -1,4 +1,13 @@
-kube_dir=${PERISH_TOP_KUBE_DIR}
+case "${1:-}" in
+  -h|--help|help)
+    print "Usage: runseal :kube [kubectl args...]"
+    print ""
+    print "Assemble KUBECONFIG from .local/kube/*.yaml and run kubectl with it."
+    exit 0
+    ;;
+esac
+
+kube_dir=${PERISH_TOP_KUBE_DIR:?kube: missing PERISH_TOP_KUBE_DIR}
 configs=$(runseal @tool fs list "$kube_dir" --glob "*.yaml" --files --require-nonempty)
 kubeconfig=$(runseal @tool string join "$configs" --separator path)
 KUBECONFIG="$kubeconfig" kubectl "$@"
diff --git a/app/tests/fixtures/estate/pr.seal b/app/tests/fixtures/estate/pr.seal
index e2c0979..3a7565b 100644
--- a/app/tests/fixtures/estate/pr.seal
+++ b/app/tests/fixtures/estate/pr.seal
@@ -140,7 +140,10 @@ fi
 
 git push -u origin "$branch"
 
-pr=$(runseal @tool gitee pr create --owner "$owner" --repo "$repo" --token-file "$token_file" --base "$base" --head "$branch" --title "$message" --body "$body")
+pr=$(runseal @tool gitee pr find --owner "$owner" --repo "$repo" --token-file "$token_file" --head "$branch" --base "$base")
+if [ "$(runseal @tool json empty "$pr")" = true ]; then
+  pr=$(runseal @tool gitee pr create --owner "$owner" --repo "$repo" --token-file "$token_file" --base "$base" --head "$branch" --title "$message" --body "$body")
+fi
 number=$(runseal @tool json get "$pr" .number)
 url=$(runseal @tool json get "$pr" .html_url)
 
diff --git a/app/tests/internal_tool.rs b/app/tests/internal_tool.rs
index dabf063..38e4855 100644
--- a/app/tests/internal_tool.rs
+++ b/app/tests/internal_tool.rs
@@ -3,6 +3,13 @@
 mod archive;
 #[path = "internal_tool/gitee.rs"]
 mod gitee;
+#[path = "internal_tool/github.rs"]
+#[cfg(unix)]
+mod github;
+#[path = "internal_tool/hash_version.rs"]
+mod hash_version;
+#[path = "internal_tool/process.rs"]
+mod process;
 #[path = "internal_tool/ssh.rs"]
 mod ssh;
 #[path = "internal_tool/string.rs"]
@@ -41,6 +48,16 @@ fn tool_runs_without_profile() {
             ],
             "123\n",
         ),
+        (
+            vec![
+                "@tool",
+                "json",
+                "has",
+                r#"{"guard":{"version":{"hash":"x"}}}"#,
+                ".guard.version.hash",
+            ],
+            "true\n",
+        ),
         (vec!["@tool", "string", "trim", "  value  "], "value\n"),
         (
             vec![
@@ -100,6 +117,10 @@ fn tool_help_is_progressive() {
             vec!["@tool", "json", "get", "--help"],
             "Usage: runseal @tool json get <json> <path>",
         ),
+        (
+            vec!["@tool", "json", "has", "--help"],
+            "Usage: runseal @tool json has <json> <path>",
+        ),
         (
             vec!["@tool", "json", "pretty", "--help"],
             "Usage: runseal @tool json pretty <mode> [args]",
@@ -204,8 +225,8 @@ fn richer_help() {
             "Build one exact-match redirect rule payload as JSON.",
         ),
         (
-            vec!["@tool", "github", "pr", "checks", "probe", "--help"],
-            "usage: runseal @tool github pr checks probe <number>",
+            vec!["@tool", "github", "issue", "comment", "create", "--help"],
+            "--prefix-enable=<true|false>",
         ),
         (
             vec!["@tool", "gitee", "pr", "merge", "--help"],
@@ -215,6 +236,10 @@ fn richer_help() {
             vec!["@tool", "archive", "local", "import", "--help"],
             "Decrypt one .local-style directory archive into the source directory.",
         ),
+        (
+            vec!["@tool", "process", "write", "--help"],
+            "<stdout|stderr> <path> [--append] -- <command> [args...]",
+        ),
     ] {
         let output = bin()
             .current_dir(&cwd)
diff --git a/app/tests/internal_tool/gitee.rs b/app/tests/internal_tool/gitee.rs
index c934631..95b5e8d 100644
--- a/app/tests/internal_tool/gitee.rs
+++ b/app/tests/internal_tool/gitee.rs
@@ -23,8 +23,8 @@ fn gitee_pr() {
         |request| {
             assert!(request.starts_with("POST /repos/perishme/perish.top/pulls "));
             assert!(request.contains("authorization: token file-token"));
-            assert!(request.contains(r#""title":"Land change""#));
-            assert!(request.contains(r#""access_token":"file-token""#));
+            assert!(request.contains("Land change"));
+            assert!(request.contains("file-token"));
         },
         r#"{"number":42,"html_url":"https://gitee.test/pr/42"}"#,
     );
@@ -64,8 +64,8 @@ fn gitee_pr() {
         |request| {
             assert!(request.starts_with("PUT /repos/perishme/perish.top/pulls/42/merge "));
             assert!(request.contains("authorization: token env-token"));
-            assert!(request.contains(r#""merge_method":"squash""#));
-            assert!(request.contains(r#""access_token":"env-token""#));
+            assert!(request.contains("squash"));
+            assert!(request.contains("env-token"));
         },
         r#"{"merged":true}"#,
     );
@@ -95,6 +95,151 @@ fn gitee_pr() {
     let payload: serde_json::Value =
         serde_json::from_slice(&merge.stdout).expect("stdout should be JSON");
     assert_eq!(payload["merged"], true);
+
+    let (api_base, handle) = mock_gitee(
+        |request| {
+            assert!(request.starts_with(
+                "GET /repos/perishme/perish.top/pulls?head=feat%2Fseal&state=open&base=main "
+            ));
+            assert!(request.contains("authorization: token env-token"));
+        },
+        r#"[{"number":42,"head":{"ref":"feat/seal"},"base":{"ref":"main"},"html_url":"https://gitee.test/pr/42"}]"#,
+    );
+    let find = bin()
+        .current_dir(&cwd)
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITEE_API_BASE", api_base)
+        .env("GITEE_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "gitee",
+            "pr",
+            "find",
+            "--owner",
+            "perishme",
+            "--repo",
+            "perish.top",
+            "--head",
+            "feat/seal",
+            "--base",
+            "main",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(find.status.success());
+    handle.join().expect("mock server should finish");
+    let payload: serde_json::Value =
+        serde_json::from_slice(&find.stdout).expect("stdout should be JSON");
+    assert_eq!(payload["number"], 42);
+
+    let (api_base, handle) = mock_gitee(
+        |request| {
+            assert!(request.starts_with(
+                "GET /repos/perishme/perish.top/pulls?head=feat%2Fmissing&state=open "
+            ));
+            assert!(request.contains("authorization: token env-token"));
+        },
+        r#"[]"#,
+    );
+    let find_none = bin()
+        .current_dir(&cwd)
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITEE_API_BASE", api_base)
+        .env("GITEE_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "gitee",
+            "pr",
+            "find",
+            "--owner",
+            "perishme",
+            "--repo",
+            "perish.top",
+            "--head",
+            "feat/missing",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(find_none.status.success());
+    handle.join().expect("mock server should finish");
+    let payload: serde_json::Value =
+        serde_json::from_slice(&find_none.stdout).expect("stdout should be JSON");
+    assert!(payload.is_null());
+
+    let (api_base, handle) = mock_gitee(
+        |request| {
+            assert!(
+                request.starts_with(
+                    "GET /repos/perishme/perish.top/pulls?head=feat%2Fdup&state=open "
+                )
+            );
+            assert!(request.contains("authorization: token env-token"));
+        },
+        r#"[{"number":42,"head":{"ref":"feat/dup"},"base":{"ref":"main"}},{"number":43,"head":{"label":"perishme:feat/dup"},"base":{"label":"perishme:main"}}]"#,
+    );
+    let find_ambiguous = bin()
+        .current_dir(&cwd)
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITEE_API_BASE", api_base)
+        .env("GITEE_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "gitee",
+            "pr",
+            "find",
+            "--owner",
+            "perishme",
+            "--repo",
+            "perish.top",
+            "--head",
+            "feat/dup",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(!find_ambiguous.status.success());
+    handle.join().expect("mock server should finish");
+    assert!(
+        String::from_utf8_lossy(&find_ambiguous.stderr)
+            .contains("Gitee PR find is ambiguous for head `feat/dup`: found 2 matches")
+    );
+
+    let (api_base, handle) = mock_gitee(
+        |request| {
+            assert!(request.starts_with("POST /repos/perishme/perish.top/pulls "));
+            assert!(request.contains("authorization: token custom-env-token"));
+            assert!(request.contains("Env override"));
+        },
+        r#"{"number":77,"html_url":"https://gitee.test/pr/77"}"#,
+    );
+    let create_with_token_env = bin()
+        .current_dir(&cwd)
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITEE_API_BASE", api_base)
+        .env("CUSTOM_GITEE_TOKEN", "custom-env-token")
+        .args([
+            "@tool",
+            "gitee",
+            "pr",
+            "create",
+            "--owner",
+            "perishme",
+            "--repo",
+            "perish.top",
+            "--token-env",
+            "CUSTOM_GITEE_TOKEN",
+            "--base",
+            "main",
+            "--head",
+            "feat/env",
+            "--title",
+            "Env override",
+            "--body",
+            "Body",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(create_with_token_env.status.success());
+    handle.join().expect("mock server should finish");
 }
 
 #[test]
diff --git a/app/tests/internal_tool/github.rs b/app/tests/internal_tool/github.rs
new file mode 100644
index 0000000..42000a6
--- /dev/null
+++ b/app/tests/internal_tool/github.rs
@@ -0,0 +1,438 @@
+#![cfg(unix)]
+
+use std::{
+    ffi::OsString,
+    io::{Read, Write},
+    net::TcpListener,
+    path::{Path, PathBuf},
+    process::Command,
+    thread,
+};
+
+use tempfile::TempDir;
+
+fn bin() -> Command {
+    Command::new(env!("CARGO_BIN_EXE_runseal"))
+}
+
+#[test]
+fn issue_comment_write() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("repo");
+    let bin_dir = temp.path().join("bin");
+    std::fs::create_dir_all(&cwd).expect("cwd should be created");
+    std::fs::create_dir_all(&bin_dir).expect("bin dir should be created");
+    write_git_stub(
+        &bin_dir.join("git"),
+        "git@gitee.com:perishme/perish.top.git",
+        "feat/prefix",
+    );
+
+    let body_file = cwd.join("body.md");
+    std::fs::write(&body_file, "Hello from file\n").expect("body file should be written");
+    let token_file = cwd.join("github.env");
+    std::fs::write(&token_file, "GITHUB_TOKEN=file-token\n").expect("token file should be written");
+
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("POST /repos/PerishCode/runseal/issues/46/comments "));
+            assert!(request.contains("authorization: Bearer file-token"));
+            assert!(request.contains(
+                r#"Requested-By-Repo: perishme/perish.top\nRequested-By-Branch: feat/prefix\n\nHello from file\n"#
+            ));
+        },
+        r#"{"id":46,"html_url":"https://github.test/comment/46"}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "comment",
+            "create",
+            "--repo",
+            "PerishCode/runseal",
+            "--number",
+            "46",
+            "--body-file",
+            body_file.to_str().unwrap(),
+            "--prefix-enable=true",
+            "--token-file",
+            token_file.to_str().unwrap(),
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+
+    let payload: serde_json::Value =
+        serde_json::from_slice(&output.stdout).expect("stdout should be JSON");
+    assert_eq!(payload["id"], 46);
+
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("PATCH /repos/perishme/perish.top/issues/77 "));
+            assert!(request.contains("authorization: Bearer explicit-token"));
+            assert!(request.contains(r#""body":"Already prefixed""#));
+        },
+        r#"{"number":77,"html_url":"https://github.test/issues/77"}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "body",
+            "update",
+            "--repo",
+            "perishme/perish.top",
+            "--number",
+            "77",
+            "--body",
+            "Already prefixed",
+            "--prefix-enable=true",
+            "--token",
+            "explicit-token",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+}
+
+#[test]
+fn issue_create() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("repo");
+    let bin_dir = temp.path().join("bin");
+    std::fs::create_dir_all(&cwd).expect("cwd should be created");
+    std::fs::create_dir_all(&bin_dir).expect("bin dir should be created");
+    write_git_stub(
+        &bin_dir.join("git"),
+        "git@gitee.com:perishme/perish.top.git",
+        "feat/prefix",
+    );
+
+    let body_file = cwd.join("body.md");
+    std::fs::write(&body_file, "Issue body\n").expect("body file should be written");
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("POST /repos/PerishCode/runseal/issues "));
+            assert!(request.contains("authorization: Bearer env-token"));
+            assert!(request.contains(r#""title":"Open one issue""#));
+            assert!(request.contains(
+                r#"Requested-By-Repo: perishme/perish.top\nRequested-By-Branch: feat/prefix\n\nIssue body\n"#
+            ));
+        },
+        r#"{"number":88,"html_url":"https://github.test/issues/88"}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "create",
+            "--repo",
+            "PerishCode/runseal",
+            "--title",
+            "Open one issue",
+            "--body-file",
+            body_file.to_str().unwrap(),
+            "--prefix-enable=true",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+
+    let payload: serde_json::Value =
+        serde_json::from_slice(&output.stdout).expect("stdout should be JSON");
+    assert_eq!(payload["number"], 88);
+}
+
+#[test]
+fn issue_prefix_rules() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("repo");
+    let bin_dir = temp.path().join("bin");
+    std::fs::create_dir_all(&cwd).expect("cwd should be created");
+    std::fs::create_dir_all(&bin_dir).expect("bin dir should be created");
+    write_git_stub(&bin_dir.join("git"), "", "feat/prefix");
+
+    let failed = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "comment",
+            "create",
+            "--repo",
+            "PerishCode/runseal",
+            "--number",
+            "46",
+            "--body",
+            "Hello",
+            "--prefix-enable=true",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(!failed.status.success());
+    assert!(
+        String::from_utf8_lossy(&failed.stderr).contains("cannot parse owner/repo from origin url"),
+        "stderr: {}",
+        String::from_utf8_lossy(&failed.stderr)
+    );
+
+    write_git_stub(
+        &bin_dir.join("git"),
+        "git@gitee.com:perishme/perish.top.git",
+        "feat/prefix",
+    );
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("POST /repos/example/demo/issues/12/comments "));
+            assert!(request.contains(r#""body":"Hello""#));
+            assert!(!request.contains("Requested-By-Repo:"));
+        },
+        r#"{"id":12}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "comment",
+            "create",
+            "--repo",
+            "example/demo",
+            "--number",
+            "12",
+            "--body",
+            "Hello",
+            "--prefix-enable=true",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+}
+
+#[test]
+fn issue_body_max() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("repo");
+    let bin_dir = temp.path().join("bin");
+    std::fs::create_dir_all(&cwd).expect("cwd should be created");
+    std::fs::create_dir_all(&bin_dir).expect("bin dir should be created");
+    write_git_stub(
+        &bin_dir.join("git"),
+        "git@gitee.com:perishme/perish.top.git",
+        "feat/prefix",
+    );
+
+    let too_long = "x".repeat(101);
+    let failed = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "comment",
+            "create",
+            "--repo",
+            "example/demo",
+            "--number",
+            "12",
+            "--body",
+            &too_long,
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(!failed.status.success());
+    assert!(
+        String::from_utf8_lossy(&failed.stderr).contains("body length 101 exceeds --body-max=100"),
+        "stderr: {}",
+        String::from_utf8_lossy(&failed.stderr)
+    );
+
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("POST /repos/example/demo/issues/12/comments "));
+            assert!(request.contains(r#""body":"#));
+        },
+        r#"{"id":12}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "comment",
+            "create",
+            "--repo",
+            "example/demo",
+            "--number",
+            "12",
+            "--body",
+            &too_long,
+            "--body-max=0",
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+
+    let body_update = "y".repeat(150);
+    let (api_base, handle) = mock_github(
+        |request| {
+            assert!(request.starts_with("PATCH /repos/example/demo/issues/12 "));
+            assert!(request.contains(r#""body":"#));
+        },
+        r#"{"number":12}"#,
+    );
+    let output = bin()
+        .current_dir(&cwd)
+        .env("PATH", prepend_path_for_test(&bin_dir))
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .env("RUNSEAL_GITHUB_API_BASE", api_base)
+        .env("GITHUB_TOKEN", "env-token")
+        .args([
+            "@tool",
+            "github",
+            "issue",
+            "body",
+            "update",
+            "--repo",
+            "example/demo",
+            "--number",
+            "12",
+            "--body",
+            &body_update,
+        ])
+        .output()
+        .expect("runseal should run");
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+}
+
+fn write_git_stub(path: &Path, origin: &str, branch: &str) {
+    write_executable(
+        path,
+        &format!(
+            r#"#!/usr/bin/env sh
+set -eu
+if [ "$1" = "remote" ] && [ "${{2:-}}" = "get-url" ] && [ "${{3:-}}" = "origin" ]; then
+  printf '%s\n' '{}'
+  exit 0
+fi
+if [ "$1" = "branch" ] && [ "${{2:-}}" = "--show-current" ]; then
+  printf '%s\n' '{}'
+  exit 0
+fi
+exit 1
+"#,
+            origin, branch
+        ),
+    );
+}
+
+fn write_executable(path: &Path, content: &str) {
+    use std::os::unix::fs::PermissionsExt;
+
+    std::fs::write(path, content).expect("stub should be written");
+    let mut permissions = std::fs::metadata(path)
+        .expect("stub metadata should be readable")
+        .permissions();
+    permissions.set_mode(0o755);
+    std::fs::set_permissions(path, permissions).expect("stub should be executable");
+}
+
+fn prepend_path_for_test(bin_dir: &Path) -> OsString {
+    let mut paths = vec![PathBuf::from(bin_dir)];
+    if let Some(existing) = std::env::var_os("PATH") {
+        paths.extend(std::env::split_paths(&existing));
+    }
+    std::env::join_paths(paths).expect("PATH should be joinable")
+}
+
+fn mock_github<F>(assert_request: F, body: &'static str) -> (String, thread::JoinHandle<()>)
+where
+    F: FnOnce(&str) + Send + 'static,
+{
+    let server = TcpListener::bind("127.0.0.1:0").expect("mock server should bind");
+    let address = server
+        .local_addr()
+        .expect("mock server address should exist");
+    let handle = thread::spawn(move || {
+        let (mut stream, _) = server.accept().expect("mock request should arrive");
+        let mut request = [0_u8; 8192];
+        let read = stream
+            .read(&mut request)
+            .expect("request should be readable");
+        let request = String::from_utf8_lossy(&request[..read]);
+        assert_request(&request);
+        write!(
+            stream,
+            "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
+            body.len(),
+            body
+        )
+        .expect("response should be written");
+    });
+    (format!("http://{address}"), handle)
+}
diff --git a/app/tests/internal_tool/hash_version.rs b/app/tests/internal_tool/hash_version.rs
new file mode 100644
index 0000000..335e1ee
--- /dev/null
+++ b/app/tests/internal_tool/hash_version.rs
@@ -0,0 +1,103 @@
+use tempfile::TempDir;
+
+use super::bin;
+
+#[test]
+fn version_atoms() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("empty");
+    std::fs::create_dir_all(&cwd).expect("empty cwd should be created");
+
+    for (args, expected) in [
+        (vec!["@tool", "version", "part", "v1.2.3", "minor"], "2\n"),
+        (
+            vec!["@tool", "version", "compare", "0.6.1", "0.6.0"],
+            "gt\n",
+        ),
+    ] {
+        let output = bin()
+            .current_dir(&cwd)
+            .env("RUNSEAL_HOME", temp.path().join("home"))
+            .args(args.clone())
+            .output()
+            .expect("runseal should run");
+
+        assert!(output.status.success(), "{args:?} should succeed");
+        let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+        assert_eq!(stdout, expected, "{args:?} stdout should match");
+    }
+}
+
+#[test]
+fn help() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("empty");
+    std::fs::create_dir_all(&cwd).expect("empty cwd should be created");
+
+    for (args, expected) in [
+        (
+            vec!["@tool", "hash", "--help"],
+            "Usage: runseal @tool hash <command> [args]",
+        ),
+        (
+            vec!["@tool", "hash", "tree", "--help"],
+            "Usage: runseal @tool hash tree <path>...",
+        ),
+        (
+            vec!["@tool", "version", "--help"],
+            "Usage: runseal @tool version <command> [args]",
+        ),
+        (
+            vec!["@tool", "version", "part", "--help"],
+            "Usage: runseal @tool version part <version> <major|minor|patch>",
+        ),
+        (
+            vec!["@tool", "version", "compare", "--help"],
+            "Usage: runseal @tool version compare <left> <right>",
+        ),
+    ] {
+        let output = bin()
+            .current_dir(&cwd)
+            .env("RUNSEAL_HOME", temp.path().join("home"))
+            .args(args.clone())
+            .output()
+            .expect("runseal should run");
+
+        assert!(output.status.success(), "{args:?} should succeed");
+        let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+        assert!(
+            stdout.contains(expected),
+            "{args:?} should contain {expected:?}, got {stdout:?}"
+        );
+    }
+}
+
+#[test]
+fn hash_tree() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("hash");
+    std::fs::create_dir_all(cwd.join("nested")).expect("tree should be created");
+    std::fs::write(cwd.join("a.txt"), "alpha\n").expect("a.txt should be written");
+    std::fs::write(cwd.join("nested/b.txt"), "beta\n").expect("b.txt should be written");
+
+    let first = bin()
+        .current_dir(temp.path())
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .args(["@tool", "hash", "tree", cwd.to_str().unwrap()])
+        .output()
+        .expect("runseal should run");
+    assert!(first.status.success());
+
+    let second = bin()
+        .current_dir(temp.path())
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .args(["@tool", "hash", "tree", cwd.to_str().unwrap()])
+        .output()
+        .expect("runseal should run");
+    assert!(second.status.success());
+
+    let first_stdout = String::from_utf8(first.stdout).expect("stdout should be UTF-8");
+    let second_stdout = String::from_utf8(second.stdout).expect("stdout should be UTF-8");
+    assert_eq!(first_stdout, second_stdout);
+    assert_eq!(first_stdout.trim().len(), 64);
+}
diff --git a/app/tests/internal_tool/process.rs b/app/tests/internal_tool/process.rs
new file mode 100644
index 0000000..4ed8395
--- /dev/null
+++ b/app/tests/internal_tool/process.rs
@@ -0,0 +1,73 @@
+use tempfile::TempDir;
+
+use super::bin;
+
+#[test]
+fn process_write_routes_streams() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("empty");
+    std::fs::create_dir_all(&cwd).expect("empty cwd should be created");
+    let output_path = cwd.join("logs").join("stderr.txt");
+
+    let output = bin()
+        .current_dir(&cwd)
+        .env("RUNSEAL_HOME", temp.path().join("home"))
+        .args([
+            "@tool",
+            "process",
+            "write",
+            "stderr",
+            output_path.to_str().expect("path should be utf-8"),
+            "--",
+            "sh",
+            "-c",
+            "printf 'out\\n'; printf 'err\\n' >&2",
+        ])
+        .output()
+        .expect("runseal should run");
+
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(String::from_utf8(output.stdout).unwrap(), "out\n");
+    assert_eq!(std::fs::read_to_string(&output_path).unwrap(), "err\n");
+}
+
+#[test]
+fn process_write_appends() {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let cwd = temp.path().join("empty");
+    std::fs::create_dir_all(&cwd).expect("empty cwd should be created");
+    let output_path = cwd.join("stdout.txt");
+
+    for value in ["one", "two"] {
+        let mut args = vec![
+            "@tool".to_string(),
+            "process".to_string(),
+            "write".to_string(),
+            "stdout".to_string(),
+            output_path
+                .to_str()
+                .expect("path should be utf-8")
+                .to_string(),
+        ];
+        if value == "two" {
+            args.push("--append".to_string());
+        }
+        args.push("--".to_string());
+        args.push("printf".to_string());
+        args.push(format!("{value}\\n"));
+
+        let output = bin()
+            .current_dir(&cwd)
+            .env("RUNSEAL_HOME", temp.path().join("home"))
+            .args(&args)
+            .output()
+            .expect("runseal should run");
+        assert!(output.status.success(), "{args:?} should succeed");
+    }
+
+    assert_eq!(std::fs::read_to_string(&output_path).unwrap(), "one\ntwo\n");
+}
diff --git a/app/tests/internal_wrappers.rs b/app/tests/internal_wrappers.rs
index 18cb9c0..cf9c948 100644
--- a/app/tests/internal_wrappers.rs
+++ b/app/tests/internal_wrappers.rs
@@ -223,6 +223,130 @@ fi
     assert_eq!(stdout, "HELLO seal from seal-tool\n");
 }
 
+#[test]
+fn seal_captures_local_output() {
+    let fx = fixture();
+    make_seal_wrapper(
+        &fx.project_wrappers.join("capture-local.seal"),
+        r#"
+helper() {
+  print "hello $1"
+}
+
+value=$(helper seal)
+print "$value"
+"#,
+    );
+
+    let output = run_in(&fx, &[":capture-local"]);
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert_eq!(stdout, "hello seal\n");
+}
+
+#[test]
+fn seal_argv_positional() {
+    let fx = fixture();
+    make_seal_wrapper(
+        &fx.project_wrappers.join("argv-positional.seal"),
+        r#"
+print() {
+  printf '%s\n' "$1"
+}
+
+fail() {
+  print "$1"
+  exit 1
+}
+
+__seal_argc=$#
+__seal_help=false
+body=
+message=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --body)
+      if [ "$#" -lt 2 ]; then fail "missing value for --body"; fi
+      body=$2
+      shift 2
+      ;;
+    --body=*)
+      body=${1#--body=}
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -h|--help|help)
+      __seal_help=true
+      shift
+      ;;
+    *)
+      if [ -z "$message" ]; then
+        message=$1
+        shift
+      else
+        fail "unexpected argument: $1"
+      fi
+      ;;
+  esac
+done
+
+print "$body|$message"
+"#,
+    );
+
+    let output = run_in(&fx, &[":argv-positional", "--body=demo", "hello"]);
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert_eq!(stdout, "demo|hello\n");
+}
+
+#[test]
+fn seal_argv_multiline_guard() {
+    let fx = fixture();
+    make_seal_wrapper(
+        &fx.project_wrappers.join("argv-multiline-guard.seal"),
+        r#"
+print() {
+  printf '%s\n' "$1"
+}
+
+fail() {
+  print "$1"
+  exit 1
+}
+
+__seal_argc=$#
+__seal_help=false
+body=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --body)
+      if [ "$#" -lt 2 ]; then
+        fail "missing value for --body"
+      fi
+      body=$2
+      shift 2
+      ;;
+    *) fail "unknown option: $1" ;;
+  esac
+done
+
+print "$body"
+"#,
+    );
+
+    let output = run_in(&fx, &[":argv-multiline-guard", "--body", "demo"]);
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert_eq!(stdout, "demo\n");
+}
+
 #[test]
 fn seal_wrapper_shadows() {
     let fx = fixture();
@@ -237,7 +361,7 @@ fn seal_wrapper_shadows() {
 }
 
 #[test]
-fn seal_env_overlay() {
+fn seal_env_overlay_fails() {
     let fx = fixture();
     make_seal_wrapper(
         &fx.project_wrappers.join("env-tool.seal"),
@@ -248,9 +372,10 @@ RUNSEAL_MARKER=sealed sh -c 'printf %s "$RUNSEAL_MARKER"'
 
     let output = run_in(&fx, &[":env-tool"]);
 
-    assert!(output.status.success());
-    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
-    assert_eq!(stdout, "sealed");
+    assert!(!output.status.success());
+    let stderr = String::from_utf8(output.stderr).expect("stderr should be UTF-8");
+    assert!(stderr.contains("shell-specific construct is not supported in .seal"));
+    assert!(stderr.contains("sh -c"));
 }
 
 #[test]
diff --git a/app/tests/operator.rs b/app/tests/operator.rs
index 4cef94b..c46ca46 100644
--- a/app/tests/operator.rs
+++ b/app/tests/operator.rs
@@ -2,6 +2,8 @@
 mod cloudflare;
 #[path = "operator/estate.rs"]
 mod estate;
+#[path = "operator/guard.rs"]
+mod guard;
 #[path = "operator/init.rs"]
 mod init;
 #[path = "operator/repo.rs"]
diff --git a/app/tests/operator/estate.rs b/app/tests/operator/estate.rs
index ece69d9..d607e67 100644
--- a/app/tests/operator/estate.rs
+++ b/app/tests/operator/estate.rs
@@ -404,6 +404,23 @@ fn admin_archive() {
     assert!(String::from_utf8_lossy(&import.stdout).contains("admin import: restored .local"));
 }
 
+#[test]
+fn kube_help() {
+    let fx = fixture();
+
+    let output = run_wrapper(&fx, "kube", &["--help"]);
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(log(&fx), "");
+    assert_eq!(
+        String::from_utf8(output.stdout).expect("stdout should be UTF-8"),
+        "Usage: runseal :kube [kubectl args...]\n\nAssemble KUBECONFIG from .local/kube/*.yaml and run kubectl with it.\n"
+    );
+}
+
 #[test]
 fn kube_env() {
     let fx = fixture();
@@ -435,6 +452,19 @@ fn kube_env() {
     );
 }
 
+#[test]
+fn kube_requires_matching_files() {
+    let fx = fixture();
+    std::fs::create_dir_all(fx.project.join(".local/kube")).expect("kube dir should be created");
+
+    let output = run_wrapper(&fx, "kube", &["auth", "whoami"]);
+    assert!(
+        !output.status.success(),
+        "wrapper should fail without kube files"
+    );
+    assert_eq!(log(&fx), "");
+}
+
 fn set_mode(path: &Path, mode: u32) {
     use std::os::unix::fs::PermissionsExt;
 
diff --git a/app/tests/operator/estate/pr.rs b/app/tests/operator/estate/pr.rs
index 1a68418..61b1929 100644
--- a/app/tests/operator/estate/pr.rs
+++ b/app/tests/operator/estate/pr.rs
@@ -13,7 +13,7 @@ fn api_flow() {
     std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
     std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
         .expect("token file should be written");
-    let (api_base, handle) = mock_gitee_sequence("feat/seal", true);
+    let (api_base, handle) = mock_gitee_sequence("feat/seal", true, false);
 
     let output = run_wrapper_env(
         &fx,
@@ -43,7 +43,7 @@ fn default_branch() {
     std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
     std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
         .expect("token file should be written");
-    let (api_base, handle) = mock_gitee_sequence("auto/land-change", true);
+    let (api_base, handle) = mock_gitee_sequence("auto/land-change", true, false);
 
     let output = run_wrapper_env(
         &fx,
@@ -95,7 +95,7 @@ fn no_merge() {
     std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
     std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
         .expect("token file should be written");
-    let (api_base, handle) = mock_gitee_sequence("feat/no-merge", false);
+    let (api_base, handle) = mock_gitee_sequence("feat/no-merge", false, false);
 
     let output = run_wrapper_env(
         &fx,
@@ -117,6 +117,36 @@ fn no_merge() {
     );
 }
 
+#[test]
+fn reuse_existing_pr() {
+    let fx = fixture();
+    let secrets = fx.project.join(".local/secrets");
+    std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
+    std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
+        .expect("token file should be written");
+    let (api_base, handle) = mock_gitee_sequence("feat/reuse", false, true);
+
+    let output = run_wrapper_env(
+        &fx,
+        "pr",
+        &["--branch", "feat/reuse", "--no-merge", "Reuse existing"],
+        &[("RUNSEAL_GITEE_API_BASE", api_base)],
+    );
+
+    assert!(
+        output.status.success(),
+        "stdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    handle.join().expect("mock server should finish");
+    assert!(String::from_utf8_lossy(&output.stdout).contains("https://gitee.test/pr/42"));
+    assert_eq!(
+        log(&fx),
+        "git|checkout|-b|feat/reuse\ngit|add|-A\ngit|commit|-m|Reuse existing\ngit|push|-u|origin|feat/reuse\ngit|checkout|main\n"
+    );
+}
+
 #[test]
 fn resume_local() {
     let fx = fixture();
@@ -124,7 +154,7 @@ fn resume_local() {
     std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
     std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
         .expect("token file should be written");
-    let (api_base, handle) = mock_gitee_sequence("feat/resume", true);
+    let (api_base, handle) = mock_gitee_sequence("feat/resume", true, true);
 
     let output = run_wrapper_env(
         &fx,
@@ -157,7 +187,7 @@ fn resume_remote() {
     std::fs::create_dir_all(&secrets).expect("secrets dir should exist");
     std::fs::write(secrets.join("gitee.env"), "GITEE_TOKEN=test-token\n")
         .expect("token file should be written");
-    let (api_base, handle) = mock_gitee_sequence("feat/remote", true);
+    let (api_base, handle) = mock_gitee_sequence("feat/remote", true, true);
 
     let output = run_wrapper_env(
         &fx,
@@ -225,13 +255,17 @@ fn resume_clean() {
 fn mock_gitee_sequence(
     expected_head: &'static str,
     merge: bool,
+    existing_pr: bool,
 ) -> (String, thread::JoinHandle<()>) {
     let server = TcpListener::bind("127.0.0.1:0").expect("mock server should bind");
     let address = server
         .local_addr()
         .expect("mock server address should exist");
     let handle = thread::spawn(move || {
-        let mut expected = vec![("POST", "/repos/perishme/perish.top/pulls")];
+        let mut expected = vec![("GET", "/repos/perishme/perish.top/pulls")];
+        if !existing_pr {
+            expected.push(("POST", "/repos/perishme/perish.top/pulls"));
+        }
         if merge {
             expected.push(("POST", "/repos/perishme/perish.top/pulls/42/review"));
             expected.push(("POST", "/repos/perishme/perish.top/pulls/42/test"));
@@ -244,14 +278,38 @@ fn mock_gitee_sequence(
                 .read(&mut request)
                 .expect("request should be readable");
             let request = String::from_utf8_lossy(&request[..read]);
-            assert!(
-                request.starts_with(&format!("{} {} ", expected.0, expected.1)),
-                "unexpected request: {request}"
-            );
+            if expected.0 == "GET" {
+                assert!(
+                    request.starts_with(&format!("{} {}?", expected.0, expected.1)),
+                    "unexpected request: {request}"
+                );
+            } else {
+                assert!(
+                    request.starts_with(&format!("{} {} ", expected.0, expected.1)),
+                    "unexpected request: {request}"
+                );
+            }
             assert!(request.contains("authorization: token test-token"));
-            assert!(request.contains(r#""access_token":"test-token""#));
             let body = if index == 0 {
-                assert!(request.contains(&format!(r#""head":"{expected_head}""#)));
+                assert!(request.contains(&format!("head={}", expected_head.replace('/', "%2F"))));
+                assert!(request.contains("state=open"));
+                if request.contains("base=main") {
+                } else {
+                    panic!("expected base=main filter in request: {request}");
+                }
+                if existing_pr {
+                    Box::leak(
+                        format!(
+                            r#"[{{"number":42,"head":{{"ref":"{expected_head}"}},"base":{{"ref":"main"}},"html_url":"https://gitee.test/pr/42"}}]"#
+                        )
+                        .into_boxed_str(),
+                    )
+                } else {
+                    r#"[]"#
+                }
+            } else if !existing_pr && index == 1 {
+                assert!(request.contains("test-token"));
+                assert!(request.contains(expected_head));
                 r#"{"number":42,"html_url":"https://gitee.test/pr/42"}"#
             } else {
                 r#"{}"#
diff --git a/app/tests/operator/guard.rs b/app/tests/operator/guard.rs
new file mode 100644
index 0000000..9f1bd52
--- /dev/null
+++ b/app/tests/operator/guard.rs
@@ -0,0 +1,220 @@
+#![cfg(unix)]
+
+use std::{
+    ffi::OsString,
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+use tempfile::TempDir;
+
+struct Fixture {
+    _temp: TempDir,
+    project: PathBuf,
+    bin: PathBuf,
+}
+
+fn fixture() -> Fixture {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let project = temp.path().join("project");
+    let bin = temp.path().join("bin");
+    std::fs::create_dir_all(project.join(".runseal/wrappers"))
+        .expect("wrapper dir should be created");
+    std::fs::create_dir_all(project.join("app/tests")).expect("app tests dir should be created");
+    std::fs::create_dir_all(&bin).expect("bin dir should be created");
+
+    std::fs::write(project.join("runseal.toml"), "injections = []\n")
+        .expect("profile should be written");
+    std::fs::write(
+        project.join(".runseal/wrappers/guard.seal"),
+        std::fs::read_to_string(repo_root().join(".runseal/wrappers/guard.seal"))
+            .expect("repo guard seal should be readable"),
+    )
+    .expect("guard seal should be copied");
+    std::fs::write(project.join("app/tests/sample.txt"), "sample\n")
+        .expect("sample test file should be written");
+
+    write_executable(
+        &bin.join("git"),
+        r#"#!/usr/bin/env sh
+set -eu
+if [ "${1:-}" = "rev-parse" ] && [ "${2:-}" = "--show-toplevel" ]; then
+  printf '%s\n' "${RUNSEAL_TEST_ROOT:?}"
+  exit 0
+fi
+exit 0
+"#,
+    );
+    write_executable(
+        &bin.join("cargo"),
+        r#"#!/usr/bin/env sh
+set -eu
+if [ "${1:-}" = "metadata" ]; then
+  if [ -n "${RUNSEAL_TEST_CARGO_METADATA:-}" ]; then
+    printf '%s\n' "$RUNSEAL_TEST_CARGO_METADATA"
+  else
+    printf '%s\n' '{"packages":[{"version":"0.6.1"}]}'
+  fi
+  exit 0
+fi
+exit 0
+"#,
+    );
+    write_executable(
+        &bin.join("curl"),
+        r#"#!/usr/bin/env sh
+set -eu
+out=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -o)
+      out="$2"
+      shift 2
+      ;;
+    -w)
+      shift 2
+      ;;
+    -s|-S)
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+if [ -n "${RUNSEAL_TEST_CURL_BODY:-}" ] && [ -n "$out" ]; then
+  printf '%s' "$RUNSEAL_TEST_CURL_BODY" > "$out"
+fi
+printf '%s' "${RUNSEAL_TEST_CURL_STATUS:-404}"
+"#,
+    );
+    write_executable(
+        &bin.join("cat"),
+        r#"#!/usr/bin/env sh
+set -eu
+/bin/cat "$@"
+"#,
+    );
+
+    Fixture {
+        _temp: temp,
+        project,
+        bin,
+    }
+}
+
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .expect("app dir should have repo parent")
+        .to_path_buf()
+}
+
+fn write_executable(path: &Path, content: &str) {
+    use std::os::unix::fs::PermissionsExt;
+
+    std::fs::write(path, content).expect("stub should be written");
+    let mut permissions = std::fs::metadata(path)
+        .expect("stub metadata should be readable")
+        .permissions();
+    permissions.set_mode(0o755);
+    std::fs::set_permissions(path, permissions).expect("stub should be executable");
+}
+
+fn prepend_path(first: &Path) -> OsString {
+    let mut paths = vec![first.to_path_buf()];
+    if let Some(runseal_dir) = Path::new(env!("CARGO_BIN_EXE_runseal")).parent() {
+        paths.push(runseal_dir.to_path_buf());
+    }
+    if let Some(existing) = std::env::var_os("PATH") {
+        paths.extend(std::env::split_paths(&existing));
+    }
+    std::env::join_paths(paths).expect("PATH should be joinable")
+}
+
+fn run_guard(fx: &Fixture, args: &[&str], envs: &[(&str, &str)]) -> std::process::Output {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_runseal"));
+    command
+        .current_dir(&fx.project)
+        .env("PATH", prepend_path(&fx.bin))
+        .env("RUNSEAL_TEST_ROOT", &fx.project)
+        .arg("-p")
+        .arg(fx.project.join("runseal.toml"))
+        .arg(":guard")
+        .args(args);
+    for (key, value) in envs {
+        command.env(key, value);
+    }
+    command.output().expect("guard should run")
+}
+
+#[test]
+fn version_hash() {
+    let fx = fixture();
+
+    let wrapper = run_guard(&fx, &["version-hash"], &[]);
+    assert!(
+        wrapper.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&wrapper.stderr)
+    );
+
+    let tool = Command::new(env!("CARGO_BIN_EXE_runseal"))
+        .current_dir(&fx.project)
+        .env("PATH", prepend_path(&fx.bin))
+        .env("RUNSEAL_HOME", fx.project.join(".home"))
+        .args(["@tool", "hash", "tree", "app/tests"])
+        .output()
+        .expect("hash tool should run");
+    assert!(tool.status.success());
+
+    assert_eq!(wrapper.stdout, tool.stdout);
+}
+
+#[test]
+fn skip_no_stable() {
+    let fx = fixture();
+
+    let output = run_guard(
+        &fx,
+        &["version-check"],
+        &[("RUNSEAL_TEST_CURL_STATUS", "404")],
+    );
+
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert!(
+        String::from_utf8_lossy(&output.stdout)
+            .contains("guard version policy: no stable metadata; skipping")
+    );
+}
+
+#[test]
+fn reject_hash_change_patch() {
+    let fx = fixture();
+
+    let output = run_guard(
+        &fx,
+        &["version-check"],
+        &[
+            (
+                "RUNSEAL_TEST_CARGO_METADATA",
+                r#"{"packages":[{"version":"0.6.1"}]}"#,
+            ),
+            ("RUNSEAL_TEST_CURL_STATUS", "200"),
+            (
+                "RUNSEAL_TEST_CURL_BODY",
+                r#"{"stableVersion":"0.6.0","guard":{"version":{"hash":"different"}}}"#,
+            ),
+        ],
+    );
+
+    assert!(!output.status.success());
+    assert!(
+        String::from_utf8_lossy(&output.stderr)
+            .contains("changed guard.version.hash requires a minor-or-higher bump")
+    );
+}
diff --git a/app/tests/operator/init.rs b/app/tests/operator/init.rs
index cc61bcb..790f42b 100644
--- a/app/tests/operator/init.rs
+++ b/app/tests/operator/init.rs
@@ -48,7 +48,10 @@ fn write_required_files(project: &Path) {
         "manage.sh",
         "manage.ps1",
         "runseal.toml",
+        ".runseal/hooks/pre-commit",
+        ".runseal/hooks/commit-msg",
         ".runseal/wrappers/cloudflare.seal",
+        ".runseal/wrappers/guard.seal",
         ".runseal/wrappers/init.seal",
         ".runseal/wrappers/pr.seal",
         ".runseal/wrappers/release.seal",
@@ -72,6 +75,24 @@ fn write_required_files(project: &Path) {
             .expect("repo init seal should be readable"),
     )
     .expect("init seal should be copied");
+    std::fs::write(
+        project.join(".runseal/wrappers/guard.seal"),
+        std::fs::read_to_string(repo_root().join(".runseal/wrappers/guard.seal"))
+            .expect("repo guard seal should be readable"),
+    )
+    .expect("guard seal should be copied");
+    std::fs::write(
+        project.join(".runseal/hooks/pre-commit"),
+        std::fs::read_to_string(repo_root().join(".runseal/hooks/pre-commit"))
+            .expect("repo pre-commit hook should be readable"),
+    )
+    .expect("pre-commit hook should be copied");
+    std::fs::write(
+        project.join(".runseal/hooks/commit-msg"),
+        std::fs::read_to_string(repo_root().join(".runseal/hooks/commit-msg"))
+            .expect("repo commit-msg hook should be readable"),
+    )
+    .expect("commit-msg hook should be copied");
     std::fs::write(project.join("runseal.toml"), "injections = []\n")
         .expect("profile should be written");
 }
@@ -133,7 +154,7 @@ fn init_installs_generated_hooks() {
     let pre_commit_text = std::fs::read_to_string(&pre_commit).expect("pre-commit should exist");
     let commit_msg_text = std::fs::read_to_string(&commit_msg).expect("commit-msg should exist");
     assert!(pre_commit_text.contains("runseal init hook"));
-    assert!(pre_commit_text.contains(".runseal/wrappers/init.seal"));
+    assert!(pre_commit_text.contains("runseal :guard"));
     assert!(commit_msg_text.contains("runseal init hook"));
 }
 
diff --git a/app/tests/operator/repo.rs b/app/tests/operator/repo.rs
index a829945..de07754 100644
--- a/app/tests/operator/repo.rs
+++ b/app/tests/operator/repo.rs
@@ -34,6 +34,11 @@ case "${1:-}" in
     [ "${2:-}" = "--show-current" ] || exit 9
     printf '%s\n' "${RUNSEAL_TEST_BRANCH:-feat/seal}"
     ;;
+  remote)
+    [ "${2:-}" = "get-url" ] || exit 9
+    [ "${3:-}" = "origin" ] || exit 9
+    printf '%s\n' "${RUNSEAL_TEST_REMOTE_ORIGIN:-git@github.com:PerishCode/runseal.git}"
+    ;;
   rev-parse)
     printf '%s\n' "${RUNSEAL_TEST_REF_SHA:-abc123}"
     ;;
@@ -326,7 +331,6 @@ git push -u origin feat/seal
 gh pr list --head feat/seal --json number,title,state,url,isDraft
 gh pr create --base develop --head feat/seal --title Seal migration --body-file body.md
 gh pr list --head feat/seal --json number,title,state,url,isDraft
-gh pr checks 77
 gh pr checks 77 --watch --interval 10
 gh pr merge 77 --squash --delete-branch
 "
diff --git a/app/tests/transpile.rs b/app/tests/transpile.rs
index 91765a7..ecfdbb6 100644
--- a/app/tests/transpile.rs
+++ b/app/tests/transpile.rs
@@ -61,7 +61,7 @@ esac
 
 fn powershell_source() -> &'static str {
     r#"
-$channel = $(if ($env:RUNSEAL_CHANNEL) { $env:RUNSEAL_CHANNEL } else { 'stable' })
+$channel = $(if ([string]::IsNullOrEmpty($env:RUNSEAL_CHANNEL)) { 'stable' } else { $env:RUNSEAL_CHANNEL })
 function release_run {
     if ([string]::IsNullOrEmpty($channel)) {
         throw 'channel missing'
@@ -124,6 +124,13 @@ print "$run_id"
 "#
 }
 
+fn redirect_source() -> &'static str {
+    r#"
+gh run list --json databaseId > build/openapi.json
+gh run view 123 2>> build/errors.log
+"#
+}
+
 fn powershell_json_get_source() -> &'static str {
     r#"
 $raw = '[{"databaseId":123}]'
@@ -159,10 +166,37 @@ fn sealir_without_profile() {
     let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
     let payload: serde_json::Value = serde_json::from_str(&stdout).expect("stdout should be JSON");
     assert_eq!(payload["version"], 1);
-    assert!(stdout.contains("env_default"));
+    assert!(stdout.contains("default_if_unset_or_empty"));
     assert!(stdout.contains("exec_checked"));
 }
 
+#[test]
+fn redirect_ir_and_targets() {
+    let fx = fixture(redirect_source());
+
+    let sealir = run_transpile(&fx, "seal", "sealir");
+    assert!(sealir.status.success());
+    let sealir = String::from_utf8(sealir.stdout).expect("stdout should be UTF-8");
+    assert!(sealir.contains("exec_write"));
+    assert!(sealir.contains("stdout"));
+    assert!(sealir.contains("stderr"));
+
+    let bash = run_transpile(&fx, "seal", "bash");
+    let powershell = run_transpile(&fx, "seal", "powershell");
+    assert!(bash.status.success());
+    assert!(powershell.status.success());
+    let bash = String::from_utf8(bash.stdout).expect("stdout should be UTF-8");
+    let powershell = String::from_utf8(powershell.stdout).expect("stdout should be UTF-8");
+    assert!(bash.contains("gh run list --json databaseId > build/openapi.json"));
+    assert!(bash.contains("gh run view 123 2>> build/errors.log"));
+    assert!(
+        powershell.contains("& 'gh' 'run' 'list' '--json' 'databaseId' > 'build/openapi.json'")
+    );
+    assert!(powershell.contains("& 'gh' 'run' 'view' '123' 2>> 'build/errors.log'"));
+    syntax::assert_bash(&bash);
+    syntax::assert_pwsh(&powershell);
+}
+
 #[test]
 fn bash_frontend_sealir() {
     let fx = fixture(sample_source());
@@ -171,7 +205,7 @@ fn bash_frontend_sealir() {
 
     assert!(output.status.success());
     let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
-    assert!(stdout.contains("env_default"));
+    assert!(stdout.contains("default_if_unset_or_empty"));
     assert!(stdout.contains("exec_checked"));
 }
 
@@ -183,7 +217,7 @@ fn powershell_frontend_sealir() {
 
     assert!(output.status.success());
     let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
-    assert!(stdout.contains("env_default"));
+    assert!(stdout.contains("default_if_unset_or_empty"));
     assert!(stdout.contains("call_function"));
     assert!(stdout.contains("exec_checked"));
 }
@@ -424,7 +458,13 @@ fn hyphen_exec() {
 
 #[test]
 fn metacharacters_fail() {
-    for source in ["printf ok | cat\n", "eval something\n"] {
+    for source in [
+        "printf ok | cat\n",
+        "eval something\n",
+        "echo ok 2>&1\n",
+        "exec echo ok\n",
+        "sh -c 'echo ok'\n",
+    ] {
         let fx = fixture(source);
 
         let output = run_transpile(&fx, "seal", "sealir");
@@ -432,7 +472,7 @@ fn metacharacters_fail() {
         assert!(!output.status.success(), "{source:?} should fail");
         let stderr = String::from_utf8(output.stderr).expect("stderr should be UTF-8");
         assert!(
-            stderr.contains("unsupported"),
+            stderr.contains("unsupported") || stderr.contains("shell-specific construct"),
             "expected unsupported error, got {stderr:?}"
         );
     }
diff --git a/app/tests/transpile_cases.rs b/app/tests/transpile_cases.rs
index 1980a21..3dc76cf 100644
--- a/app/tests/transpile_cases.rs
+++ b/app/tests/transpile_cases.rs
@@ -4,6 +4,8 @@ mod argv;
 mod command_predicate;
 #[path = "transpile_cases/env.rs"]
 mod env;
+#[path = "transpile_cases/expansion.rs"]
+mod expansion;
 #[path = "transpile_cases/regex.rs"]
 mod regex;
 #[path = "transpile_cases/release.rs"]
diff --git a/app/tests/transpile_cases/argv.rs b/app/tests/transpile_cases/argv.rs
index 6824a56..a65e243 100644
--- a/app/tests/transpile_cases/argv.rs
+++ b/app/tests/transpile_cases/argv.rs
@@ -98,6 +98,67 @@ print "$body_file"
 "#
 }
 
+fn argv_positional_source() -> &'static str {
+    r#"
+__seal_argc=$#
+__seal_help=false
+body=
+message=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --body)
+      if [ "$#" -lt 2 ]; then fail "missing value for --body"; fi
+      body=$2
+      shift 2
+      ;;
+    --body=*)
+      body=${1#--body=}
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -h|--help|help)
+      __seal_help=true
+      shift
+      ;;
+    *)
+      if [ -z "$message" ]; then
+        message=$1
+        shift
+      else
+        fail "unexpected argument: $1"
+      fi
+      ;;
+  esac
+done
+print "$body"
+print "$message"
+"#
+}
+
+fn argv_multiline_guard_source() -> &'static str {
+    r#"
+__seal_argc=$#
+__seal_help=false
+body=
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --body)
+      if [ "$#" -lt 2 ]; then
+        fail "missing value for --body"
+      fi
+      body=$2
+      shift 2
+      ;;
+    *) fail "unknown option: $1" ;;
+  esac
+done
+print "$body"
+"#
+}
+
 #[test]
 fn argv_parse_roundtrip() {
     for input_lang in ["seal", "bash"] {
@@ -133,3 +194,64 @@ fn argv_parse_emits_targets() {
     super::syntax::assert_bash(&bash);
     super::syntax::assert_pwsh(&powershell);
 }
+
+#[test]
+fn argv_positional_roundtrip() {
+    let fx = fixture(argv_positional_source());
+    let output = run_transpile(&fx, "seal", "sealir");
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert!(stdout.contains("\"positional\""));
+    assert!(stdout.contains("\"name\": \"message\""));
+    assert!(stdout.contains("\"extra_error\": \"unexpected argument: $1\""));
+}
+
+#[test]
+fn argv_positional_targets() {
+    let fx = fixture(argv_positional_source());
+
+    let bash = run_transpile(&fx, "seal", "bash");
+    let powershell = run_transpile(&fx, "seal", "powershell");
+
+    assert!(bash.status.success());
+    assert!(powershell.status.success());
+    let bash = String::from_utf8(bash.stdout).expect("stdout should be UTF-8");
+    let powershell = String::from_utf8(powershell.stdout).expect("stdout should be UTF-8");
+    assert!(bash.contains("body=${1#--body=}"));
+    assert!(bash.contains("if [ -z \"$message\" ]; then"));
+    assert!(powershell.contains("$body = $__seal_arg.Substring(7)"));
+    assert!(powershell.contains("if ([string]::IsNullOrEmpty($message)) {"));
+    assert!(powershell.contains("$message = $__seal_arg"));
+    super::syntax::assert_bash(&bash);
+    super::syntax::assert_pwsh(&powershell);
+}
+
+#[test]
+fn argv_multiline_guard_roundtrip() {
+    let fx = fixture(argv_multiline_guard_source());
+    let output = run_transpile(&fx, "seal", "sealir");
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert!(stdout.contains("argv_parse"));
+    assert!(stdout.contains("\"name\": \"body\""));
+}
+
+#[test]
+fn argv_multiline_guard_targets() {
+    let fx = fixture(argv_multiline_guard_source());
+
+    let bash = run_transpile(&fx, "seal", "bash");
+    let powershell = run_transpile(&fx, "seal", "powershell");
+
+    assert!(bash.status.success());
+    assert!(powershell.status.success());
+    let bash = String::from_utf8(bash.stdout).expect("stdout should be UTF-8");
+    let powershell = String::from_utf8(powershell.stdout).expect("stdout should be UTF-8");
+    assert!(bash.contains("body=$2"));
+    assert!(bash.contains("shift 2"));
+    assert!(powershell.contains("$body = $args[$__seal_index + 1]"));
+    super::syntax::assert_bash(&bash);
+    super::syntax::assert_pwsh(&powershell);
+}
diff --git a/app/tests/transpile_cases/expansion.rs b/app/tests/transpile_cases/expansion.rs
new file mode 100644
index 0000000..14dd915
--- /dev/null
+++ b/app/tests/transpile_cases/expansion.rs
@@ -0,0 +1,183 @@
+use std::process::Command;
+
+use tempfile::TempDir;
+
+use super::syntax;
+
+fn bin() -> Command {
+    Command::new(env!("CARGO_BIN_EXE_runseal"))
+}
+
+struct Fixture {
+    _temp: TempDir,
+    dir: std::path::PathBuf,
+    source: std::path::PathBuf,
+}
+
+fn fixture(source: &str) -> Fixture {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let dir = temp.path().join("project-without-profile");
+    std::fs::create_dir_all(&dir).expect("project dir should be created");
+    let source_path = dir.join("operator.seal");
+    std::fs::write(&source_path, source).expect("source should be written");
+    Fixture {
+        _temp: temp,
+        dir,
+        source: source_path,
+    }
+}
+
+fn run_transpile(fx: &Fixture, input_lang: &str, output_lang: &str) -> std::process::Output {
+    bin()
+        .current_dir(&fx.dir)
+        .arg("@transpile")
+        .arg("--input-lang")
+        .arg(input_lang)
+        .arg("--output-lang")
+        .arg(output_lang)
+        .arg(&fx.source)
+        .output()
+        .expect("runseal should run")
+}
+
+fn expansion_source() -> &'static str {
+    r#"
+channel=${RUNSEAL_CHANNEL:-stable}
+required=${RUNSEAL_TOKEN:?missing token}
+target=${1:-origin}
+branch=${2:?missing branch}
+print "$channel $required $target $branch"
+"#
+}
+
+#[test]
+fn forms_roundtrip() {
+    let fx = fixture(expansion_source());
+
+    let sealir = run_transpile(&fx, "seal", "sealir");
+    assert!(sealir.status.success());
+    let sealir = String::from_utf8(sealir.stdout).expect("stdout should be UTF-8");
+    assert!(sealir.contains("require_non_empty"));
+    assert!(sealir.contains("default_if_unset_or_empty"));
+
+    let bash = run_transpile(&fx, "seal", "bash");
+    assert!(bash.status.success());
+    let bash = String::from_utf8(bash.stdout).expect("stdout should be UTF-8");
+    assert!(bash.contains("channel=\"${RUNSEAL_CHANNEL:-stable}\""));
+    assert!(bash.contains("required=\"${RUNSEAL_TOKEN:?missing token}\""));
+    assert!(bash.contains("target=\"${1:-origin}\""));
+    assert!(bash.contains("branch=\"${2:?missing branch}\""));
+    syntax::assert_bash(&bash);
+
+    let powershell = run_transpile(&fx, "seal", "powershell");
+    assert!(powershell.status.success());
+    let powershell = String::from_utf8(powershell.stdout).expect("stdout should be UTF-8");
+    assert!(powershell.contains(
+        "$channel = $(if ([string]::IsNullOrEmpty($env:RUNSEAL_CHANNEL)) { 'stable' } else { $env:RUNSEAL_CHANNEL })"
+    ));
+    assert!(powershell.contains(
+        "$required = $(if ([string]::IsNullOrEmpty($env:RUNSEAL_TOKEN)) { throw 'missing token' } else { $env:RUNSEAL_TOKEN })"
+    ));
+    assert!(powershell.contains(
+        "$target = $(if (($args.Count -lt 1) -or [string]::IsNullOrEmpty($1)) { 'origin' } else { $1 })"
+    ));
+    assert!(powershell.contains(
+        "$branch = $(if (($args.Count -lt 2) -or [string]::IsNullOrEmpty($2)) { throw 'missing branch' } else { $2 })"
+    ));
+    syntax::assert_pwsh(&powershell);
+
+    let powershell_fx = fixture(&powershell);
+    let roundtrip = run_transpile(&powershell_fx, "powershell", "sealir");
+    assert!(roundtrip.status.success());
+    let roundtrip = String::from_utf8(roundtrip.stdout).expect("stdout should be UTF-8");
+    assert!(roundtrip.contains("require_non_empty"));
+    assert!(roundtrip.contains("default_if_unset_or_empty"));
+}
+
+fn run_wrapper(source: &str, args: &[&str], env: &[(&str, &str)]) -> std::process::Output {
+    let temp = TempDir::new().expect("temp dir should be created");
+    let project = temp.path().join("project");
+    let wrappers = project.join(".runseal").join("wrappers");
+    std::fs::create_dir_all(&wrappers).expect("wrappers should be created");
+    std::fs::write(project.join("runseal.toml"), "injections = []\n")
+        .expect("profile should be written");
+    std::fs::write(wrappers.join("expansion.seal"), source).expect("wrapper should be written");
+    let mut command = bin();
+    command.current_dir(&project).arg(":expansion").args(args);
+    for (key, value) in env {
+        command.env(key, value);
+    }
+    command.output().expect("runseal should run")
+}
+
+#[test]
+fn env_default_runtime() {
+    let source = "print \"${RUNSEAL_CHANNEL:-stable}\"\n";
+    let missing = run_wrapper(source, &[], &[]);
+    assert!(missing.status.success());
+    assert_eq!(
+        String::from_utf8(missing.stdout).expect("stdout should be UTF-8"),
+        "stable\n"
+    );
+    let empty = run_wrapper(source, &[], &[("RUNSEAL_CHANNEL", "")]);
+    assert!(empty.status.success());
+    assert_eq!(
+        String::from_utf8(empty.stdout).expect("stdout should be UTF-8"),
+        "stable\n"
+    );
+}
+
+#[test]
+fn positional_default_runtime() {
+    let source = "print \"${1:-origin}\"\n";
+    let missing = run_wrapper(source, &[], &[]);
+    assert!(missing.status.success());
+    assert_eq!(
+        String::from_utf8(missing.stdout).expect("stdout should be UTF-8"),
+        "origin\n"
+    );
+    let empty = run_wrapper(source, &[""], &[]);
+    assert!(empty.status.success());
+    assert_eq!(
+        String::from_utf8(empty.stdout).expect("stdout should be UTF-8"),
+        "origin\n"
+    );
+}
+
+#[test]
+fn env_require_runtime() {
+    let source = "print \"${RUNSEAL_TOKEN:?missing token}\"\n";
+    let missing = run_wrapper(source, &[], &[]);
+    assert!(!missing.status.success());
+    assert!(
+        String::from_utf8(missing.stderr)
+            .expect("stderr should be UTF-8")
+            .contains("missing token")
+    );
+    let empty = run_wrapper(source, &[], &[("RUNSEAL_TOKEN", "")]);
+    assert!(!empty.status.success());
+    assert!(
+        String::from_utf8(empty.stderr)
+            .expect("stderr should be UTF-8")
+            .contains("missing token")
+    );
+}
+
+#[test]
+fn positional_require_runtime() {
+    let source = "print \"${1:?missing branch}\"\n";
+    let missing = run_wrapper(source, &[], &[]);
+    assert!(!missing.status.success());
+    assert!(
+        String::from_utf8(missing.stderr)
+            .expect("stderr should be UTF-8")
+            .contains("missing branch")
+    );
+    let empty = run_wrapper(source, &[""], &[]);
+    assert!(!empty.status.success());
+    assert!(
+        String::from_utf8(empty.stderr)
+            .expect("stderr should be UTF-8")
+            .contains("missing branch")
+    );
+}
diff --git a/app/tests/transpile_cases/wrappers.rs b/app/tests/transpile_cases/wrappers.rs
index 0cf45df..8993d25 100644
--- a/app/tests/transpile_cases/wrappers.rs
+++ b/app/tests/transpile_cases/wrappers.rs
@@ -220,6 +220,65 @@ echo_first "$2"
     syntax::assert_pwsh(&powershell);
 }
 
+#[test]
+fn capture_locals() {
+    let fx = fixture(
+        r#"
+helper() {
+  print "hello $1"
+}
+
+value=$(helper world)
+print "$value"
+"#,
+    );
+
+    let sealir = run_transpile(&fx, "sealir");
+    assert!(sealir.status.success());
+    let sealir = String::from_utf8(sealir.stdout).expect("stdout should be UTF-8");
+    assert!(sealir.contains("capture_function"));
+    assert!(sealir.contains("\"function\": \"helper\""));
+
+    let bash = run_transpile(&fx, "bash");
+    let powershell = run_transpile(&fx, "powershell");
+    assert!(bash.status.success());
+    assert!(powershell.status.success());
+    let bash = String::from_utf8(bash.stdout).expect("stdout should be UTF-8");
+    let powershell = String::from_utf8(powershell.stdout).expect("stdout should be UTF-8");
+    assert!(bash.contains("value=$(helper world)"));
+    assert!(powershell.contains("$value = & helper 'world'"));
+    syntax::assert_bash(&bash);
+    syntax::assert_pwsh(&powershell);
+}
+
+#[test]
+fn capture_locals_pwsh() {
+    let fx = fixture(
+        r#"
+function helper {
+    Write-Output ('hello ' + $1)
+}
+
+$value = & helper 'world'
+Write-Output $value
+"#,
+    );
+
+    let output = bin()
+        .current_dir(&fx.dir)
+        .arg("@transpile")
+        .arg("--input-lang=powershell")
+        .arg("--output-lang=sealir")
+        .arg(&fx.source)
+        .output()
+        .expect("runseal should run");
+
+    assert!(output.status.success());
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be UTF-8");
+    assert!(stdout.contains("capture_function"));
+    assert!(stdout.contains("\"function\": \"helper\""));
+}
+
 fn wrapper_source(wrapper: &str) -> String {
     std::fs::read_to_string(repo_root().join(wrapper)).expect("wrapper should be readable")
 }
diff --git a/docs/examples/README.md b/docs/examples/README.md
new file mode 100644
index 0000000..c2eb7ff
--- /dev/null
+++ b/docs/examples/README.md
@@ -0,0 +1,10 @@
+# Examples
+
+These examples capture canonical shapes that are valid but easy to get wrong
+from shell intuition alone.
+
+- [Seal `case` / argv parser shapes](./seal/case.md)
+- [GitHub tool examples](./tools/github.md)
+
+Use these as the repository-owned reference when a live wrapper or operator
+flow feels "almost shell" but still needs the exact runseal shape.
diff --git a/docs/examples/seal/case.md b/docs/examples/seal/case.md
new file mode 100644
index 0000000..9fe7a0d
--- /dev/null
+++ b/docs/examples/seal/case.md
@@ -0,0 +1,170 @@
+# Seal `case` / Argv Shapes
+
+This file documents the canonical `.seal` shapes for `case "$1" in` argv
+parsing. These are intentionally narrower than general shell scripting.
+
+## Supported option arm: `--name=value`
+
+```sh
+--body=*)
+  body=${1#--body=}
+  shift
+  ;;
+```
+
+This is the canonical inline-value string option arm.
+
+## Supported option arm: `--name <value>`
+
+Single-line guarded form:
+
+```sh
+--body)
+  if [ "$#" -lt 2 ]; then fail "missing value for --body"; fi
+  body=$2
+  shift 2
+  ;;
+```
+
+Multi-line guarded form:
+
+```sh
+--body)
+  if [ "$#" -lt 2 ]; then
+    fail "missing value for --body"
+  fi
+  body=$2
+  shift 2
+  ;;
+```
+
+Both are canonical string-option arms.
+
+The guard predicate is intentionally exact:
+
+```sh
+if [ "$#" -lt 2 ]; then
+```
+
+This is not a general parser for arbitrary pre-check logic.
+
+## Supported flag arm
+
+```sh
+--dry-run)
+  dry_run=true
+  shift
+  ;;
+```
+
+## Supported help arm
+
+```sh
+-h|--help|help)
+  __seal_help=true
+  shift
+  ;;
+```
+
+## Supported positional fallback arm
+
+This is the one supported positional sink shape:
+
+```sh
+*)
+  if [ -z "$message" ]; then
+    message=$1
+    shift
+  else
+    fail "unexpected argument: $1"
+  fi
+  ;;
+```
+
+Semantics:
+
+- The first unmatched argument fills one positional target.
+- The next unmatched argument fails with a stable operator-facing message.
+- This is not the same as "take one arg and break out of parsing."
+
+## Not supported
+
+These shapes are intentionally outside the current canonical surface:
+
+```sh
+*)
+  message=$1
+  shift
+  break
+  ;;
+```
+
+```sh
+*)
+  shift
+  ;;
+```
+
+```sh
+--body)
+  body=$2
+  shift 2
+  ;;
+```
+
+The last form looks natural in shell, but runseal currently requires the
+canonical missing-value guard for separated-value option arms.
+
+## Complete minimal example
+
+```sh
+print() {
+  printf '%s\n' "$1"
+}
+
+fail() {
+  print "$1"
+  exit 1
+}
+
+__seal_argc=$#
+__seal_help=false
+body=
+message=
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --body)
+      if [ "$#" -lt 2 ]; then
+        fail "missing value for --body"
+      fi
+      body=$2
+      shift 2
+      ;;
+    --body=*)
+      body=${1#--body=}
+      shift
+      ;;
+    -h|--help|help)
+      __seal_help=true
+      shift
+      ;;
+    *)
+      if [ -z "$message" ]; then
+        message=$1
+        shift
+      else
+        fail "unexpected argument: $1"
+      fi
+      ;;
+  esac
+done
+
+if [ "$__seal_help" = true ]; then
+  print help
+  exit 0
+fi
+
+print "$body"
+print "$message"
+```
diff --git a/docs/examples/tools/github.md b/docs/examples/tools/github.md
new file mode 100644
index 0000000..519adfe
--- /dev/null
+++ b/docs/examples/tools/github.md
@@ -0,0 +1,94 @@
+# GitHub Tool Examples
+
+These examples show the intended `runseal @tool github ...` usage patterns.
+
+Implementation is pure GitHub HTTP API. The public shape does not depend on the
+`gh` CLI.
+
+## Token resolution
+
+Priority:
+
+1. `--token`
+2. `--token-file`
+3. `--token-env`
+4. default `GITHUB_TOKEN`
+
+So the normal path is to inject `GITHUB_TOKEN` through runseal env/profile
+mechanics and keep the call site clean.
+
+## Issue comment create
+
+```bash
+runseal @tool github issue comment create \
+  --repo PerishCode/runseal \
+  --number 49 \
+  --body-file body.md
+```
+
+Default body limit:
+
+- `comment create` defaults `--body-max=100`
+- `--body-max=0` disables the limit
+- overflow fails fast; it does not truncate
+
+Example with unlimited body:
+
+```bash
+runseal @tool github issue comment create \
+  --repo PerishCode/runseal \
+  --number 49 \
+  --body-file body.md \
+  --body-max 0
+```
+
+## Issue create
+
+```bash
+runseal @tool github issue create \
+  --repo PerishCode/runseal \
+  --title "Document canonical Seal argv shapes" \
+  --body-file body.md
+```
+
+## Issue body update
+
+```bash
+runseal @tool github issue body update \
+  --repo PerishCode/runseal \
+  --number 49 \
+  --body-file body.md
+```
+
+## Cross-repo prefixing
+
+When writing from one controlled repo into another controlled repo, use
+`--prefix-enable=true` so the request origin is recorded in the body.
+
+```bash
+runseal @tool github issue comment create \
+  --repo PerishCode/runseal \
+  --number 49 \
+  --body-file body.md \
+  --body-max 0 \
+  --prefix-enable=true
+```
+
+The prefix is only applied when the repo-pair rule matches. It is not a
+generic text mutation flag.
+
+## Payload hygiene
+
+For non-trivial text, always write the body to a file first and pass
+`--body-file`.
+
+Preferred:
+
+```bash
+runseal @tool github issue comment create \
+  --repo PerishCode/runseal \
+  --number 49 \
+  --body-file body.md
+```
+
+Only use inline `--body` for a very short single-line payload.