fix(pi): add installer and runtime path guidance

scripts/install-pi-package.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ./scripts/install-pi-package.sh --global
+  ./scripts/install-pi-package.sh --local
+
+Options:
+  --global  Install the repo path into ~/.pi/agent/settings.json
+  --local   Install the repo path into .pi/settings.json for the current project
+EOF
+}
+
+require_command() {
+  local command_name=$1
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    echo "Missing required command: $command_name" >&2
+    exit 1
+  fi
+}
+
+pnpm_cmd=()
+
+resolve_pnpm() {
+  if command -v pnpm >/dev/null 2>&1; then
+    pnpm_cmd=(pnpm)
+    return
+  fi
+
+  if command -v corepack >/dev/null 2>&1; then
+    pnpm_cmd=(corepack pnpm)
+    return
+  fi
+
+  echo "Missing required command: pnpm (or corepack)" >&2
+  exit 1
+}
+
+run_pnpm() {
+  "${pnpm_cmd[@]}" "$@"
+}
+
+require_node_20() {
+  local node_major
+  node_major=$(node -p "process.versions.node.split('.')[0]")
+  if (( node_major < 20 )); then
+    echo "Node.js 20+ is required. Found Node.js $(node -v)." >&2
+    exit 1
+  fi
+}
+
+install_scope=
+if [[ $# -ne 1 ]]; then
+  usage >&2
+  exit 1
+fi
+
+case "$1" in
+  --global)
+    install_scope="global"
+    ;;
+  --local)
+    install_scope="local"
+    ;;
+  -h|--help)
+    usage
+    exit 0
+    ;;
+  *)
+    usage >&2
+    exit 1
+    ;;
+esac
+
+require_command pi
+require_command node
+require_node_20
+resolve_pnpm
+
+case "$install_scope" in
+  global)
+    pi install "$ROOT_DIR"
+    ;;
+  local)
+    pi install -l "$ROOT_DIR"
+    ;;
+esac
+
+echo "Bootstrapping Atlassian runtime dependencies..."
+run_pnpm install --frozen-lockfile --dir "${ROOT_DIR}/pi-package/skills/atlassian/scripts"
+
+echo "Bootstrapping web-automation runtime dependencies..."
+run_pnpm install --frozen-lockfile --dir "${ROOT_DIR}/pi-package/skills/web-automation/scripts"
+run_pnpm --dir "${ROOT_DIR}/pi-package/skills/web-automation/scripts" exec cloakbrowser install
+echo "Rebuilding native web-automation dependencies..."
+run_pnpm rebuild --dir "${ROOT_DIR}/pi-package/skills/web-automation/scripts" better-sqlite3 esbuild
+
+echo "Installed Pi packages now visible to this scope:"
+pi list
+
+echo "Pi package installed (${install_scope}) and runtime dependencies bootstrapped."

scripts/verify-pi-resources.sh

@@ -17,6 +17,7 @@ REQUIRED_FILES=(
   "skills/web-automation/pi/SKILL.md"
   "skills/reviewer-runtime/pi/run-review.sh"
   "skills/reviewer-runtime/pi/notify-telegram.sh"
+  "scripts/install-pi-package.sh"
   "scripts/sync-pi-package-skills.sh"
   "pi-package/skills/atlassian/SKILL.md"
   "pi-package/skills/create-plan/SKILL.md"
@@ -34,6 +35,7 @@ done
 
 test -x skills/reviewer-runtime/pi/run-review.sh
 test -x skills/reviewer-runtime/pi/notify-telegram.sh
+test -x scripts/install-pi-package.sh
 test -x scripts/sync-pi-package-skills.sh
 find skills/web-automation/pi/scripts -type f -print -quit | grep -q .
 find skills/atlassian/pi/scripts -type f -print -quit | grep -q .
@@ -43,6 +45,15 @@ for file in skills/create-plan/pi/SKILL.md skills/do-task/pi/SKILL.md skills/imp
   grep -q 'docs/PI-COMMON-REVIEWER.md' "$file"
 done
 
+grep -q 'pi-package/skills/atlassian/scripts' skills/atlassian/pi/SKILL.md
+grep -q 'pi-package/skills/web-automation/scripts' skills/web-automation/pi/SKILL.md
+grep -q 'local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`' docs/PI.md
+
+grep -q 'install-pi-package.sh --global' docs/PI.md
+grep -q 'install-pi-package.sh --local' docs/PI.md
+grep -q 'install-pi-package.sh --global' README.md
+grep -q 'install-pi-package.sh --local' README.md
+
 for family in atlassian create-plan do-task implement-plan web-automation; do
   source_dir="skills/${family}/pi"
   source_skill_md="${source_dir}/SKILL.md"
@@ -55,14 +66,19 @@ for family in atlassian create-plan do-task implement-plan web-automation; do
   test "$skill_name" = "$(basename "$mirror_dir")"
   test "$skill_name" = "$(awk '/^name:/ { print $2; exit }' "$mirror_skill_md")"
 
-  diff -qr --exclude '.DS_Store' "$source_dir" "$mirror_dir" >/dev/null
+  diff -qr \
+    --exclude '.DS_Store' \
+    --exclude 'node_modules' \
+    "$source_dir" "$mirror_dir" >/dev/null
 
   while IFS= read -r -d '' source_path; do
     rel_path=${source_path#"$source_dir"/}
     mirror_path="${mirror_dir}/${rel_path}"
     test -e "$mirror_path"
     test "$(stat -f '%Lp' "$source_path")" = "$(stat -f '%Lp' "$mirror_path")"
-  done < <(find "$source_dir" -mindepth 1 -print0)
+  done < <(find "$source_dir" \
+    \( -name '.DS_Store' -o -name 'node_modules' \) -prune -o \
+    -mindepth 1 -print0)
 done
 
 ! grep -nE 'update_plan|plan mode|sub-agent|subagents' \
@@ -100,6 +116,7 @@ if (!Array.isArray(pkg.files) || pkg.files.length === 0) {
 for (const requiredFile of [
   "pi-package/skills",
   "docs/PI-COMMON-REVIEWER.md",
+  "scripts/install-pi-package.sh",
   "scripts/sync-pi-package-skills.sh",
 ]) {
   if (!pkg.files.includes(requiredFile)) {