fix(pi): add installer and runtime path guidance

docs/PI.md

@@ -52,13 +52,39 @@ Workflow-heavy Pi skills split their shared setup across two docs:
 
 ## Package Install
 
-The repo-level package manifest lives at root so Pi can install directly from this checkout:
+The user-facing install flow is the repo-owned installer script, not a raw `pi install` command.
+
+Global install from a cloned checkout:
 
 ```bash
-pi install -l "$(pwd)"
-pi list
+./scripts/install-pi-package.sh --global
 ```
 
+Project-local install from a cloned checkout:
+
+```bash
+./scripts/install-pi-package.sh --local
+```
+
+Prerequisites for that one-liner:
+
+- Node.js 20+
+- `pi`
+- either `pnpm` on `PATH`, or Node's bundled `corepack` support
+
+The installer uses `pnpm` directly when available and falls back to `corepack pnpm` otherwise.
+The root `package.json` pins the pnpm version so Corepack-backed installs resolve consistently.
+
+That script:
+
+- runs `pi install` in the chosen scope
+- installs the nested runtime dependencies for `atlassian`
+- installs the nested runtime dependencies for `web-automation`
+- fetches the CloakBrowser binary for `web-automation`
+- prints `pi list` at the end so the active install is visible immediately
+
+For this cloned-checkout flow, local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`. Pi loads the skills from the package mirror in this repo; it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` unless you do a manual copy install.
+
 The package surface intentionally ships:
 
 - `pi-package/skills/**`
@@ -89,12 +115,15 @@ When a source Pi variant changes:
 npm pack --dry-run --json
 ```
 
+The installer intentionally does not run sync. It assumes the checked-in `pi-package/skills/*` mirror is already current.
+
 The verifier is responsible for catching:
 
 - missing mirror directories
 - source/mirror drift
 - package metadata pointing at the wrong skill roots
 - missing shared Pi docs
+- missing user-facing installer wiring
 
 ## Extension Decision