From e408cac0d7d903ccfcecfb906d4e48292294ab55 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 11 Oct 2026 00:46:19 +0200
Subject: [PATCH] docs(pi): update installation and remote login guidance
 (#17836)

---
 docs/user/install.md                      |  2 +-
 docs/user/providers-pi.md                 | 23 ++++++++++++++++++++---
 packages/provider-pi/src/server/status.ts |  2 +-
 3 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/user/install.md b/docs/user/install.md
index 67df94217ac36877626708e678569a962844413a..2a5023e9253eb78559d819011b70e1fd9abe6cc2 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -142,7 +142,7 @@ computer.
 | Grok Build  | Install [Grok Build CLI](https://x.ai/cli), then run `grok login`.                                                                                        |
 | OpenCode    | Install [OpenCode](https://opencode.ai), then run `opencode auth login`.                                                                                  |
 | Antigravity | Install and sign in with Google from T3 Code's provider settings.                                                                                         |
-| Pi          | Install [Pi](https://pi.dev), then run `pi` once to finish its login or API-key setup.                                                                    |
+| Pi          | Install [Pi](./providers-pi.md#set-up-pi) with Node.js 22.19 or newer, then run `pi` and `/login`.                                                        |
 | Muse Code   | Install [Muse Code](https://dev.meta.ai/docs/muse-code) on the server, run `muse login`, then enable it in Settings → Providers.                          |
 
 Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
diff --git a/docs/user/providers-pi.md b/docs/user/providers-pi.md
index f57272b4de529edf0702b4c114f479a99aa110cb..f86f9923ef8d60dc039f974e4a8c2925d891be48 100644
--- a/docs/user/providers-pi.md
+++ b/docs/user/providers-pi.md
@@ -5,17 +5,34 @@ extensions, skills, context files, and native session history.
 
 ## Set Up Pi
 
-1. Install Pi on the machine running the T3 Code server. Pi 1.0 is recommended; 0.80.5 is the
-   oldest version T3 Code supports.
-2. Run Pi once in a terminal and finish the provider login or API-key setup you normally use.
+1. Install [Pi](https://pi.dev) on the machine running the T3 Code server. Pi requires Node.js
+   22.19 or newer; its platform installers can install Node if needed. T3 Code supports Pi
+   0.80.5 or newer.
+2. Run `pi` in a terminal, then `/login` to connect your model provider or configure its API key.
 3. Open T3 Code Settings, enable Pi, and refresh the provider.
 
+For an npm installation, use:
+
+```sh
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
 If `pi` is not on the server's `PATH`, set Pi's binary path to the executable. Provider environment
 variables and launch arguments are also available for installations that need a custom agent
 directory, endpoint, or model configuration. `--provider` must be paired with `--model`. T3 Code
 rejects launch arguments that change Pi's execution mode or select a session because T3 owns those
 parts of the process lifecycle.
 
+On a remote or headless server, connect to that machine over SSH and run `pi`, then `/login`.
+Open the authorization URL on your own computer. If the callback cannot reach the server,
+paste the final redirect URL or authorization code back into Pi when prompted. You can also
+set your model provider's API-key environment variable in the Pi instance's settings; mark
+secret values as sensitive.
+
+Update installer-managed Pi with `pi update`. If another package manager owns the installation,
+update it through that manager instead. For example, a Nix profile installation uses
+`nix profile upgrade pi`.
+
 ## What Carries Over
 
 T3 Code discovers the models reported by Pi and exposes their supported thinking levels. The
diff --git a/packages/provider-pi/src/server/status.ts b/packages/provider-pi/src/server/status.ts
index 0ff054c4f63cd5c9e9cac8cd0e3855ef8de8a565..ab6d6f7d9874badb5365f40b68b492efae21c5ab 100644
--- a/packages/provider-pi/src/server/status.ts
+++ b/packages/provider-pi/src/server/status.ts
@@ -303,7 +303,7 @@ export const checkPiProviderStatus = Effect.fn("checkPiProviderStatus")(function
         status: "error",
         auth: { status: "unknown" },
         message: isCommandMissingCause(error)
-          ? "Pi CLI (`pi`) is not installed or not on PATH. Install with `npm install -g @earendil-works/pi-coding-agent`."
+          ? "Pi CLI (`pi`) is not installed or not on PATH. Install with `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`."
           : "Failed to execute Pi CLI health check.",
       },
     });
-- 
2.54.0