fix: address deep-review findings on docs site branch

- docs: fix broken cross-page anchors in bytecode, recipes, build and
  sea-mode guides; replace raw /pkg/ prefixed link in index.md with
  VitePress-managed markdown link.
- ci(xcompile): switch cross-compile matrix to workflow_dispatch only
  (manual trigger is safer and avoids burning macOS/Windows minutes on
  every PR), wire the node-majors input via a setup job, add timeouts,
  upload per-cell build logs, short-circuit collate when no results,
  fix empty-array expansion under bash 3.2 / set -u on macOS runners,
  add spawnSync timeout, sanitise backticks in PR summary, and drop
  the dead PR-comment path.
- ci(docs): split concurrency so PR builds no longer queue behind
  production deploys, scope pages/id-token permissions to the deploy
  job, add timeout-minutes, and add an offline lychee link-check step
  to catch dead anchors before they ship.
- chore(skills): make run-matrix.sh fail fast (set -euo pipefail),
  write per-cell logs under $WORKDIR/logs so a failing cell is not
  overwritten, print log paths on stderr, add an unknown-target case,
  and document the debugging workflow in SKILL.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: robertsLando

.claude/skills/pkg-xcompile-test/SKILL.md

@@ -179,6 +179,38 @@ GitHub Actions' `macos-13` / `macos-14` runners are the right place for
 that; a follow-up CI workflow that runs the hello.js matrix there would
 close the last hole.
 
+## Debugging a failing run
+
+Each cell writes its own log; paths are printed on stderr next to any
+`FAIL` and re-summarised at the end of the run.
+
+- **Log location** — `$PKG_XCOMPILE_WORKDIR/logs/node<major>/build-<mode>-<target>.log`
+  (and `run-<mode>-<target>.log`). Default workdir is `/tmp/pkg-xcompile`.
+  Logs are per-cell so a failing build is not overwritten by the next one.
+- **Re-run one cell** — the fastest way is still to invoke `pkg` directly
+  against the same fixture:
+  ```bash
+  cd /tmp/pkg-xcompile
+  node /path/to/pkg/lib-es5/bin.js hello.js -t node22-linux-arm64 \
+    -o /tmp/pkg-xcompile/bin-node22/std-linux-arm64
+  ```
+- **`exec format error` on arm64 runs** — binfmt is not registered. After
+  a reboot `tonistiigi/binfmt` needs to be re-installed:
+  ```bash
+  docker run --privileged --rm tonistiigi/binfmt --install arm64
+  ```
+- **Wine cell always FAIL** — pull the image manually once
+  (`docker pull scottyhardy/docker-wine`) and inspect
+  `logs/node<major>/run-sea-win-x64.log` for the actual crash. The
+  EBADF-stdout gotcha is documented above.
+- **SEA FAIL on Node 20** — expected; pkg enforces `host node ≥ 22` for SEA.
+- **`Error: UNEXPECTED-20` / silent exit (EXIT=4)** — these are the
+  tracked Node-22 Standard-mode regressions (issues #181 and #87). Not
+  environment bugs — see [Node 22 results](#node-22) below.
+- **Stale binary hiding a regression** — pkg does not hash its own source
+  into the output. After rebuilding pkg, delete `bin-node<major>/` before
+  re-running the matrix.
+
 ## The script
 
 The harness lives next to this `SKILL.md` as `run-matrix.sh`. Before

.claude/skills/pkg-xcompile-test/run-matrix.sh

@@ -13,11 +13,15 @@
 # the repo stays clean. The tiny hello.js + package.json fixtures are kept
 # next to this script and copied into the workdir on first run.
 #
+# Per-cell logs are written to $PKG_XCOMPILE_WORKDIR/logs/ and their paths
+# are printed to stderr next to any FAIL so a failing cell can be inspected
+# without re-running the whole matrix.
+#
 # Builds a tiny hello.js for every {mode,target} combination and runs what
 # can be executed on this Linux host (native x64, arm64 via docker+qemu,
 # win-x64 via scottyhardy/docker-wine). macOS runtime is skipped (no KVM).
 
-set -u
+set -euo pipefail
 
 NODE_MAJOR="${1:-22}"
 
@@ -28,7 +32,8 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 PKG_BIN="${2:-$REPO_ROOT/lib-es5/bin.js}"
 WORKDIR="${PKG_XCOMPILE_WORKDIR:-/tmp/pkg-xcompile}"
 BINDIR="$WORKDIR/bin-node$NODE_MAJOR"
-mkdir -p "$BINDIR"
+LOGDIR="$WORKDIR/logs/node$NODE_MAJOR"
+mkdir -p "$WORKDIR" "$BINDIR" "$LOGDIR"
 
 if [[ ! -f "$PKG_BIN" ]]; then
   echo "pkg not built at $PKG_BIN — run 'yarn build' in $REPO_ROOT first." >&2
@@ -49,7 +54,11 @@ if command -v nvm >/dev/null 2>&1; then
     exit 1
   }
 fi
-echo "Host node: $(node -v)"
+HOST_NODE_VER="$(node -v)"
+echo "Host node: $HOST_NODE_VER" >&2
+if [[ "$HOST_NODE_VER" != v${NODE_MAJOR}.* ]]; then
+  echo "WARN: host node major ($HOST_NODE_VER) != requested ($NODE_MAJOR) — SEA builds may misbehave" >&2
+fi
 
 # --- Prepare tiny test project ----------------------------------------------
 if [[ ! -f "$WORKDIR/hello.js" ]]; then
@@ -69,61 +78,95 @@ MODES=(std std-public sea)
 
 declare -A RESULT  # RESULT[mode/target] = "BUILD / RUN"
 
+# build_one: writes "OK" | "MISSING" | "FAIL" to stdout, progress/log path
+# to stderr. Always returns 0 so command substitution never aborts the loop.
 build_one() {
   local mode="$1" target="$2"
   local out="$BINDIR/${mode}-${target}"
   [[ "$target" == win-* ]] && out="${out}.exe"
+  local buildlog="$LOGDIR/build-${mode}-${target}.log"
 
   local args=(hello.js -t "node${NODE_MAJOR}-${target}" -o "$out")
   case "$mode" in
     sea) args+=(--sea) ;;
     std-public) args+=(--public-packages '*' --public) ;;
   esac
 
-  echo "  build: $mode → $target"
-  if (cd "$WORKDIR" && node "$PKG_BIN" "${args[@]}" >/tmp/pkg-build.log 2>&1); then
-    [[ -f "$out" ]] && echo "OK" || echo "MISSING"
+  echo "  build: $mode → $target" >&2
+  if (cd "$WORKDIR" && node "$PKG_BIN" "${args[@]}" >"$buildlog" 2>&1); then
+    if [[ -f "$out" ]]; then
+      echo "OK"
+    else
+      echo "MISSING"
+      echo "    log: $buildlog" >&2
+    fi
   else
     echo "FAIL"
+    echo "    log: $buildlog" >&2
   fi
+  return 0
 }
 
+# run_one: same stdout/stderr contract as build_one.
 run_one() {
   local mode="$1" target="$2"
   local bin="$BINDIR/${mode}-${target}"
   [[ "$target" == win-* ]] && bin="${bin}.exe"
-  [[ ! -f "$bin" ]] && { echo "SKIP-no-bin"; return; }
+  if [[ ! -f "$bin" ]]; then
+    echo "SKIP-no-bin"
+    return 0
+  fi
+  local runlog="$LOGDIR/run-${mode}-${target}.log"
 
   case "$target" in
     linux-x64)
-      "$bin" </dev/null >/tmp/pkg-run.log 2>&1 && grep -q "hello from pkg" /tmp/pkg-run.log && echo "OK" || echo "FAIL"
+      if "$bin" </dev/null >"$runlog" 2>&1 && grep -q "hello from pkg" "$runlog"; then
+        echo "OK"
+      else
+        echo "FAIL"
+        echo "    log: $runlog" >&2
+      fi
       ;;
     linux-arm64)
-      docker run --rm --platform linux/arm64 -v "$BINDIR:/mnt" ubuntu:latest \
-        "/mnt/$(basename "$bin")" </dev/null >/tmp/pkg-run.log 2>&1 \
-        && grep -q "hello from pkg" /tmp/pkg-run.log && echo "OK" || echo "FAIL"
+      if docker run --rm --platform linux/arm64 -v "$BINDIR:/mnt" ubuntu:latest \
+          "/mnt/$(basename "$bin")" </dev/null >"$runlog" 2>&1 \
+        && grep -q "hello from pkg" "$runlog"; then
+        echo "OK"
+      else
+        echo "FAIL"
+        echo "    log: $runlog" >&2
+      fi
       ;;
     win-x64)
       # Wine in non-tty docker breaks Node stdout unless we redirect to a
       # file inside the container, then cat it back.
       docker run --rm -v "$BINDIR:/mnt" scottyhardy/docker-wine \
         bash -c "wine '/mnt/$(basename "$bin")' </dev/null >/tmp/out 2>/tmp/err; cat /tmp/out" \
-        >/tmp/pkg-run.log 2>/dev/null
-      grep -q "hello from pkg" /tmp/pkg-run.log && echo "OK" || echo "FAIL"
+        >"$runlog" 2>/dev/null || true
+      if grep -q "hello from pkg" "$runlog"; then
+        echo "OK"
+      else
+        echo "FAIL"
+        echo "    log: $runlog" >&2
+      fi
       ;;
     macos-*)
       echo "SKIP-no-mac"
       ;;
+    *)
+      echo "SKIP-unknown"
+      ;;
   esac
+  return 0
 }
 
 # --- Execute ----------------------------------------------------------------
 echo "=== node $NODE_MAJOR | pkg: $PKG_BIN ==="
 for mode in "${MODES[@]}"; do
   for target in "${TARGETS[@]}"; do
-    b=$(build_one "$mode" "$target" | tail -1)
+    b="$(build_one "$mode" "$target")"
     if [[ "$b" == "OK" ]]; then
-      r=$(run_one "$mode" "$target")
+      r="$(run_one "$mode" "$target")"
     else
       r="n/a"
     fi
@@ -139,3 +182,5 @@ for target in "${TARGETS[@]}"; do
   printf '%-12s | %-18s | %-18s | %-18s\n' "$target" \
     "${RESULT[std/$target]}" "${RESULT[std-public/$target]}" "${RESULT[sea/$target]}"
 done
+
+printf '\nPer-cell logs: %s\n' "$LOGDIR"