From 137547a47012119310fe13a8a542cac5ba63c521 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Mon, 18 May 2026 12:47:33 +0200
Subject: [PATCH] docs(coding-agent): add uninstall instructions

---
 packages/coding-agent/docs/index.md      |  8 ++++++++
 packages/coding-agent/docs/packages.md   |  2 ++
 packages/coding-agent/docs/quickstart.md | 20 ++++++++++++++++++++
 packages/coding-agent/docs/usage.md      |  2 ++
 4 files changed, 32 insertions(+)

diff --git a/packages/coding-agent/docs/index.md b/packages/coding-agent/docs/index.md
index a4294d3a..ffe97865 100644
--- a/packages/coding-agent/docs/index.md
+++ b/packages/coding-agent/docs/index.md
@@ -16,6 +16,14 @@ Or alternatively with npm:
 npm install -g @earendil-works/pi-coding-agent
 ```
 
+To uninstall pi itself, use npm for curl and npm installs:
+
+```bash
+npm uninstall -g @earendil-works/pi-coding-agent
+```
+
+For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @earendil-works/pi-coding-agent`, `yarn global remove @earendil-works/pi-coding-agent`, or `bun uninstall -g @earendil-works/pi-coding-agent`.
+
 Then run it in a project directory:
 
 ```bash
diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md
index 575f0acc..db5ab6cc 100644
--- a/packages/coding-agent/docs/packages.md
+++ b/packages/coding-agent/docs/packages.md
@@ -36,6 +36,8 @@ pi update npm:@foo/bar      # update one package
 pi update --extension npm:@foo/bar
 ```
 
+These commands manage pi packages, not the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall).
+
 By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup.
 
 To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
diff --git a/packages/coding-agent/docs/quickstart.md b/packages/coding-agent/docs/quickstart.md
index 55c6e346..29f9896a 100644
--- a/packages/coding-agent/docs/quickstart.md
+++ b/packages/coding-agent/docs/quickstart.md
@@ -10,6 +10,26 @@ Pi is distributed as an npm package:
 npm install -g @earendil-works/pi-coding-agent
 ```
 
+### Uninstall
+
+Use the package manager that installed pi. The curl installer uses npm globally, so curl and npm installs are removed with npm:
+
+```bash
+# curl installer or npm install -g
+npm uninstall -g @earendil-works/pi-coding-agent
+
+# pnpm
+pnpm remove -g @earendil-works/pi-coding-agent
+
+# Yarn
+yarn global remove @earendil-works/pi-coding-agent
+
+# Bun
+bun uninstall -g @earendil-works/pi-coding-agent
+```
+
+Uninstalling pi leaves settings, credentials, sessions, and installed pi packages in `~/.pi/agent/`.
+
 Then start pi in the project directory you want it to work on:
 
 ```bash
diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md
index 487e72ac..65081090 100644
--- a/packages/coding-agent/docs/usage.md
+++ b/packages/coding-agent/docs/usage.md
@@ -137,6 +137,8 @@ pi list                      # List installed packages
 pi config                    # Enable/disable package resources
 ```
 
+These commands manage pi packages, not the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall).
+
 See [Pi Packages](packages.md) for package sources and security notes.
 
 ### Modes