@piagent/platform 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.0.2 - 2026-07-25
+
+Install and uninstall become two commands each. The five-command sequence was never the shortest path; it was the only one that produced a project configuration a teammate could use.
+
+### Added
+
+- Added `piagent-uninstall`, which removes the Pi package this platform registered and nothing else. It reports by default and only acts on `--apply`, matching how install and migration already work. `--with-addons` also removes the pinned add-ons, `--with-host` the Pi host, and `--project <path>` a project's profile, lock, and runtime state. It recognises every source shape the platform has been installed as, including installs from before the namespace rename, so an old registration still comes out. Credentials, trust decisions, sessions, todos, and project memory are never removed at any flag combination; files written from templates and then edited are reported rather than deleted, and only the entry pointing at this platform is dropped from a project's `.pi/settings.json`.
+
+### Fixed
+
+- `piagent-setup` running from an installed package now writes `npm:@piagent/platform@<version>` into project settings instead of the directory it happens to be installed in. Project settings are meant to be committed, and an install path means nothing on a teammate's machine. A working checkout has no published identity to point at, so it still falls back to the local path and still says so.
+
+### Changed
+
+- Documentation now leads with `npm install -g @piagent/platform` followed by `piagent-setup`, which installs the pinned Pi host itself. The five-command sequence remains, described as the explicit path for a reviewed team rollout rather than as the only way in.
+
 ## v1.0.1 - 2026-07-25
 
 Documentation release. v1.0.0 reached the npm registry but no document told anyone it was there, so every install instruction still pointed at the Git source.

package/README.md

@@ -109,22 +109,33 @@ Supported for this release:
 | Native Windows | Not a team-rollout target yet; terminal helpers and shell policy rely on Bash/POSIX semantics. |
 | WSL2 | Experimental and not release-gated yet. |
 
-Node.js `>=22.19.0` and Pi Coding Agent `0.81.1` are required. Pi Coding Agent is installed as a Node CLI; the project release matrix above defines which OS/CPU surfaces this platform has verified.
+Node.js `>=22.19.0` is required. Two commands:
+
+```bash
+npm install -g @piagent/platform
+piagent-setup
+```
+
+`piagent-setup` installs the exact Pi Coding Agent host this release pins, installs the Pi package, initializes the current directory, and runs the doctor. Run it from the project you want to set up. It also installs the MCP baseline and subagents; pass `--no-mcp` and `--no-subagents` to skip them, or `--global-only` to install nothing into a project.
+
+Because it is running from an installed package, the source it writes into `.pi/settings.json` is `npm:@piagent/platform@<version>`, which means the same thing on a teammate's machine.
+
+To install each component explicitly instead — for a pinned team rollout where every step is reviewed:
 
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-The npm command installs the `piagent-*` terminal helpers. `piagent-install --stable` then resolves the helper's release tag to a commit SHA and installs the matching Pi package. In its output, `currentRelease` is the version of the terminal helper currently executing.
+`piagent-install --stable` resolves the helper's release tag to a commit SHA and installs the matching Pi package. In its output, `currentRelease` is the version of the terminal helper currently executing. The project release matrix above defines which OS/CPU surfaces this platform has verified.
 
 If you only need to install the Pi package and do not need the `piagent-*` terminal commands, pin the current release tag or a reviewed commit directly:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.1
+pi install git:github.com/Vt-mmm/piagent@v1.0.2
 ```
 
 From a checked-out platform repo, the same helper is available as a script:
@@ -163,6 +174,28 @@ Optional Herdr integration:
 herdr integration install pi
 ```
 
+## Uninstall
+
+`piagent-uninstall` reports what it would remove and exits. It only acts with `--apply`, because it edits Pi settings that other tools also write to.
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+```
+
+That removes the Pi package this platform registered. Everything beyond it is opt-in:
+
+```bash
+piagent-uninstall --apply --with-addons              # pi-mcp-adapter, pi-subagents, pi-web-access
+piagent-uninstall --apply --with-host                # the Pi Coding Agent host
+piagent-uninstall --apply --project /path/to/project # a project's profile, lock, and runtime state
+npm uninstall -g @piagent/platform                   # the npm-global helper, removed separately
+```
+
+Removal targets what is registered in Pi's settings rather than what the current version installs, so a package registered by an older release still comes out.
+
+Credentials, trust decisions, sessions, todos, and project memory are never removed, at any flag combination. Files written from a template and then edited — `AGENTS.md`, `.pi/settings.json`, `.pi/project-context.md` and the like — are listed for review rather than deleted. A project's `.pi/settings.json` keeps every setting except the package entry pointing at this platform.
+
 ## Daily use
 
 ```bash
@@ -423,7 +456,7 @@ Most projects do not need shell init. Use this only when you want to pre-create
 ```bash
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -538,7 +571,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.0.1` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.0.2` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -380,10 +380,10 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.0.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.1` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.0.2` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.0.2` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
-| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, npm-global helper và Pi package. v1.0.1 yêu cầu Pi `0.81.1`. |
+| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, npm-global helper và Pi package. v1.0.2 yêu cầu Pi `0.81.1`. |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá dependency risk của host cũ trước khi hạ version. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
 | `piagent-install --stable` | Cài Pi package matching với helper hiện tại bằng resolved commit SHA. |
@@ -410,6 +410,10 @@ Các lệnh này chạy ngoài Pi.
 | `piagent-setup <project> --with-web-access` | Setup project + optional web access cho research subagents. |
 | `piagent-usage /path/to/project` | Lấy exact session usage từ terminal khác. |
 | `piagent-doctor /path/to/project --strict-share` | Kiểm tra project có share/open-source được không. |
+| `piagent-uninstall` | Báo cáo những gì sẽ được gỡ. Dry run, không đụng gì. |
+| `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
+| `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm pi-mcp-adapter, pi-subagents, pi-web-access và Pi host. |
+| `piagent-uninstall --apply --project /path/to/project` | Gỡ thêm state của platform trong project: profile, lock, `piagent-state/`. |
 | `piagent-benchmark ...` | Ghi quality benchmark bằng package bin. |
 | `bash scripts/verify-local.sh` | Verify repo platform trước khi commit/tag. |
 | `bash scripts/verify-local.sh --offline` | Verify trong CI/máy sạch, bỏ qua local Pi model catalog. |

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.0.1` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.0.2` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.0.1` |
+| Registry distribution | `npm:@piagent/platform@1.0.2` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.0.1` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.0.2` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.1
+pi install git:github.com/Vt-mmm/piagent@v1.0.2
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.0.1` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.0.1`.
+`pi install git:github.com/Vt-mmm/piagent@v1.0.2` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.0.2`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -103,7 +103,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.0.1`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.0.2`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -269,7 +269,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,11 +842,15 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.0.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.1` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.0.2` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.0.2` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
-| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. v1.0.1 yêu cầu Pi `0.81.1`. |
+| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. v1.0.2 yêu cầu Pi `0.81.1`. |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
+| `piagent-uninstall` | Báo cáo sẽ gỡ những gì. Dry run, không đụng gì. |
+| `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
+| `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm add-on đã pin và Pi host. |
+| `piagent-uninstall --apply --project <path>` | Gỡ thêm profile, lock và `piagent-state/` của project. Không đụng credential, trust, session, todo, `.pi/memory/`. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
 | `piagent-install --stable` | Apply Pi package matching với helper hiện tại bằng resolved commit SHA. |
 | `piagent-install --version vX.Y.Z --resolve-tag` | Chỉ đổi Pi package; terminal helper giữ nguyên version. |
@@ -936,7 +940,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -42,7 +42,7 @@ pi install /path/to/piagent
 
 - `0.1.x`: local/internal pilot.
 - `0.2.x`: có guard ổn định và docs team.
-- `1.0.1`: đủ security review, MCP registry, adapter schema versioned.
+- `1.0.2`: đủ security review, MCP registry, adapter schema versioned.
 
 ## Không publish
 

package/docs/quickstart-vietnamese.md

@@ -26,22 +26,33 @@ Support matrix của release hiện tại:
 | Native Windows | Chưa phải target rollout team; helper/shell policy cần Bash/POSIX semantics. |
 | WSL2 | Experimental, chưa release-gate. |
 
-Node.js phải từ `22.19.0` trở lên và Pi Coding Agent phải là `0.81.1`.
+Node.js phải từ `22.19.0` trở lên. Hai lệnh:
+
+```bash
+npm install -g @piagent/platform
+piagent-setup
+```
+
+Chạy `piagent-setup` ngay trong thư mục project. Nó tự cài đúng Pi Coding Agent `0.81.1` mà release này pin, cài Pi package, khởi tạo `.pi/`, rồi chạy doctor. Nó cũng cài MCP baseline và subagents; thêm `--no-mcp`, `--no-subagents` nếu không cần, hoặc `--global-only` nếu chưa muốn đụng project nào.
+
+Vì chạy từ package đã cài, source ghi vào `.pi/settings.json` là `npm:@piagent/platform@<version>` — portable, commit được.
+
+Muốn cài tay từng lớp để kiểm soát chặt hơn:
 
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Lệnh trên cài Pi CLI, cài terminal command `piagent-*`, rồi install Pi Agent Platform bằng stable release đã resolve tag thành commit SHA. Trong output installer, `currentRelease` là version của terminal helper đang chạy. `v1.0.1` là release hiện tại của docs này.
+Lệnh trên cài Pi CLI, cài terminal command `piagent-*`, rồi install Pi Agent Platform bằng stable release đã resolve tag thành commit SHA. Trong output installer, `currentRelease` là version của terminal helper đang chạy. `v1.0.2` là release hiện tại của docs này.
 
 Nếu chỉ cần cài package vào Pi và không cần terminal command helper:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.1
+pi install git:github.com/Vt-mmm/piagent@v1.0.2
 ```
 
 Nếu đang ở source checkout của platform, có thể preview và áp stable bằng helper:
@@ -218,7 +229,7 @@ Nếu chưa có profile/tech stack, dùng select-style flow để tránh agent t
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -241,7 +252,7 @@ Script bash chỉ dùng khi muốn preseed config vào repo:
 ```bash
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -340,6 +351,28 @@ bash "$PIAGENT_PLATFORM_HOME/packages/piagent-core/skills/piagent-source-cache/c
 
 Các việc này là credential/trust boundary, không nên automation mù.
 
+## Gỡ cài đặt
+
+`piagent-uninstall` mặc định là dry run: nó in ra sẽ gỡ những gì rồi thoát, không đụng vào đâu cả. Thêm `--apply` mới thực hiện.
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+```
+
+Mặc định chỉ gỡ Pi package của platform khỏi Pi settings global. Muốn gỡ rộng hơn:
+
+```bash
+piagent-uninstall --apply --with-addons                    # + pi-mcp-adapter, pi-subagents, pi-web-access
+piagent-uninstall --apply --with-host                      # + Pi Coding Agent host
+piagent-uninstall --apply --project /path/to/project       # + profile, lock, piagent-state/ của project
+npm uninstall -g @piagent/platform                         # helper npm-global, gỡ riêng
+```
+
+Có những thứ nó **không bao giờ** xoá, kể cả khi bật hết cờ: `auth.json`, `trust.json`, `sessions/`, `todos/`, và `.pi/memory/`. Đó là dữ liệu của anh chứ không phải state của platform. `AGENTS.md`, `.pi/settings.json`, `project-context.md` cũng được giữ vì sinh ra từ template rồi anh sửa tiếp — script liệt kê chúng ra để anh tự quyết.
+
+Với `.pi/settings.json` nó chỉ bỏ đúng entry trỏ tới platform trong `packages`, phần còn lại giữ nguyên.
+
 ## Tài liệu chính
 
 - Command reference: `docs/command-reference-vietnamese.md`

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.81.1`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.0.1 | Rollout guidance |
+| Surface | Status for v1.0.2 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.0.1` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.0.2` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.0.1 (helper package version)
-tag: v1.0.1
+currentRelease: v1.0.2 (helper package version)
+tag: v1.0.2
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.1
+pi install git:github.com/Vt-mmm/piagent@v1.0.2
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -141,6 +141,44 @@ piagent-install --version vPREVIOUS --resolve-tag
 piagent-doctor /path/to/project --strict-share
 ```
 
+## Uninstall
+
+Rollback moves between releases. Uninstall leaves entirely, and it is the flow a team member or an external user reaches for when this platform is no longer wanted on their machine.
+
+`piagent-uninstall` reports and exits; `--apply` performs the removal. The default is a report because the command edits Pi's global settings, which other tools also write to.
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+```
+
+Each additional layer is opt-in, so leaving the platform never takes the Pi host or a project's history with it by surprise:
+
+```bash
+piagent-uninstall --apply --with-addons               # pi-mcp-adapter, pi-subagents, pi-web-access
+piagent-uninstall --apply --with-host                 # the exact Pi Coding Agent host
+piagent-uninstall --apply --project /path/to/project  # a project's profile, lock, and runtime state
+npm uninstall -g @piagent/platform                    # the npm-global helper, removed separately
+```
+
+Removal reads the package entries registered in Pi's settings rather than assuming what the running version installs. A machine that first installed the platform before the namespace rename still has that older entry removed.
+
+### What uninstall will not remove
+
+These are operator data, not platform state, and no flag combination deletes them:
+
+| Kept | Why |
+|---|---|
+| `.pi/auth.json`, `.pi/trust.json` | Credentials and trust decisions. Re-earning them is not a cleanup step. |
+| `.pi/sessions/`, `.pi/todos/` | Work history that predates and outlives the platform. |
+| `.pi/memory/` | Accumulated project memory. Deleting it destroys work the platform only stored. |
+
+Files written from a template and then edited in place — `AGENTS.md`, `REVIEW_GUIDELINES.md`, `.mcp.json`, `.pi/settings.json`, `.pi/mcp.json`, `.pi/project-context.md`, `.pi/context-index.json`, `.pi/tech-stack.json` — are listed rather than deleted, because by the time uninstall runs they hold project content rather than template content.
+
+`.pi/settings.json` is Pi's file, not this platform's. Uninstall drops only the `packages` entry pointing here and leaves every other setting untouched.
+
+The global MCP baseline at `$PI_CODING_AGENT_DIR/mcp.json` and the subagent config beside it are shared files that may have been edited after install. `--with-addons` reports their paths instead of resetting them.
+
 ## Canonical release checklist
 
 Production docs must never advertise a tag that cannot yet be installed.

package/docs/security-threat-model.md

@@ -21,7 +21,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.0.1, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.0.2, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable
 cd /path/to/project
 pi
@@ -41,7 +41,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -83,6 +83,20 @@ pi install npm:@your-scope/platform@x.y.z
 
 Không cần chạy bash để set profile cho từng project.
 
+### Rời platform
+
+Thành viên rời team hoặc máy không dùng platform nữa thì gỡ bằng `piagent-uninstall`. Mặc định nó chỉ báo cáo; `--apply` mới thực hiện:
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+piagent-uninstall --apply --with-addons --with-host    # gỡ luôn add-on và Pi host
+piagent-uninstall --apply --project /path/to/project   # gỡ state platform trong project
+npm uninstall -g @piagent/platform
+```
+
+Credential, trust, session, todo và `.pi/memory/` không bị xoá ở bất kỳ tổ hợp cờ nào. `.pi/settings.json` chỉ mất đúng entry trỏ tới platform. Chi tiết trong [release/install policy](release-install-policy.md).
+
 ## Bước 2 — mở project và login OAuth
 
 ```bash

package/docs-site/index.html

@@ -798,7 +798,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.0.1 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.0.2 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -927,14 +927,14 @@
             <p class="section-kicker">Quickstart</p>
             <h2>Step by step cho thành viên mới</h2>
             <p class="section-lead">
-              Luồng dưới đây là đường đi chuẩn cho team: chuẩn bị Node.js và Pi Coding Agent, cài Pi Agent Platform bằng release tag đã pin, kiểm tra compatibility, mở repo, chọn profile, bật quyền phù hợp, chạy task, rồi verify bằng command thật. Bản latest chỉ nên dùng cho máy cá nhân hoặc sandbox chấp nhận cập nhật nhanh.
+              Luồng dưới đây là đường đi chuẩn cho team: chuẩn bị Node.js và Pi Coding Agent, cài Pi Agent Platform từ npm registry theo version đã pin, kiểm tra compatibility, mở repo, chọn profile, bật quyền phù hợp, chạy task, rồi verify bằng command thật. Bản latest chỉ nên dùng cho máy cá nhân hoặc sandbox chấp nhận cập nhật nhanh.
             </p>
 
             <div class="steps">
               <article class="step">
                 <div>
                   <h3>Chuẩn bị runtime</h3>
-                  <p>Dùng Node.js 22.19.0 trở lên và Pi Coding Agent <span class="inline-code">0.81.1</span>. Pi Agent Platform <span class="inline-code">v1.0.1</span> đang pin compatibility với runtime này và công bố support matrix theo OS/CPU riêng cho platform helper.</p>
+                  <p>Dùng Node.js 22.19.0 trở lên và Pi Coding Agent <span class="inline-code">0.81.1</span>. Pi Agent Platform <span class="inline-code">v1.0.2</span> đang pin compatibility với runtime này và công bố support matrix theo OS/CPU riêng cho platform helper.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>
@@ -974,16 +974,24 @@ pi --version</code></pre>
               <article class="step">
                 <div>
                   <h3>Cài Pi Agent Platform có pin</h3>
-                  <p>Team nên cài npm-global helper trước, rồi dùng helper đó resolve stable tag thành commit SHA và cài Pi package matching. Trong output, <span class="inline-code">currentRelease</span> là version của terminal helper đang chạy. Direct Pi install chỉ dùng khi không cần command <span class="inline-code">piagent-*</span>.</p>
+                  <p>Đường ngắn nhất là hai lệnh: cài helper từ npm, rồi chạy <span class="inline-code">piagent-setup</span> ngay trong thư mục project. Lệnh đó tự cài đúng Pi host mà release này pin, cài Pi package, khởi tạo <span class="inline-code">.pi/</span> và chạy doctor. Nó cũng cài sẵn MCP baseline và subagents; thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span> nếu không muốn, hoặc <span class="inline-code">--global-only</span> nếu chưa đụng tới project nào.</p>
                   <div class="command-card">
-                    <header><span>Stable helper install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @piagent/platform@1.0.1&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-                    <pre><code>npm install -g --ignore-scripts @piagent/platform@1.0.1
+                    <header><span>Hai lệnh</span><button class="clip-btn" data-clip="npm install -g @piagent/platform&#10;piagent-setup">Lấy lệnh</button></header>
+                    <pre><code>npm install -g @piagent/platform
+piagent-setup</code></pre>
+                  </div>
+                  <p>Vì chạy từ package đã cài, source ghi vào <span class="inline-code">.pi/settings.json</span> là <span class="inline-code">npm:@piagent/platform@&lt;version&gt;</span> — giá trị này có nghĩa như nhau trên máy đồng đội, nên commit được.</p>
+                  <p>Muốn kiểm soát từng lớp thì cài tay: helper trước, rồi dùng helper đó resolve stable tag thành commit SHA và cài Pi package matching. Trong output, <span class="inline-code">currentRelease</span> là version của terminal helper đang chạy. Direct Pi install chỉ dùng khi không cần command <span class="inline-code">piagent-*</span>.</p>
+                  <p>Hai thành phần này lấy từ hai nguồn khác nhau, và đó là chủ ý. Helper là tarball đã publish nên npm verify được provenance attestation gắn với commit build ra nó. Pi package thì dựa vào việc resolve tag thành commit SHA rồi đối chiếu với <span class="inline-code">PIAGENT_EXPECTED_RELEASE_COMMIT</span> — một phép kiểm mà version range của registry không diễn đạt được. Trỏ <span class="inline-code">stable</span> sang npm là bỏ phép kiểm đó chứ không phải thay nó, nên nguồn <span class="inline-code">git:</span> được giữ nguyên. Máy không có quyền Git tới repo này thì dùng channel <span class="inline-code">npm:@piagent/platform@x.y.z</span>.</p>
+                  <div class="command-card">
+                    <header><span>Stable helper install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @piagent/platform@1.0.2&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+                    <pre><code>npm install -g --ignore-scripts @piagent/platform@1.0.2
 piagent-install --stable --dry-run
 piagent-install --stable</code></pre>
                   </div>
                   <div class="command-card">
-                    <header><span>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.1">Lấy lệnh</button></header>
-                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.1</code></pre>
+                    <header><span>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.2">Lấy lệnh</button></header>
+                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.2</code></pre>
                   </div>
                 </div>
               </article>
@@ -1019,6 +1027,26 @@ pi update --extensions</code></pre>
                 </div>
               </article>
 
+              <article class="step">
+                <div>
+                  <h3>Gỡ cài đặt khi không dùng nữa</h3>
+                  <p><span class="inline-code">piagent-uninstall</span> mặc định chỉ in ra sẽ gỡ những gì rồi thoát; phải thêm <span class="inline-code">--apply</span> nó mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào. Mặc định chỉ gỡ Pi package của platform; add-on, Pi host và state trong project đều là opt-in.</p>
+                  <div class="command-card">
+                    <header><span>Gỡ</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply&#10;npm uninstall -g @piagent/platform">Lấy lệnh</button></header>
+                    <pre><code>piagent-uninstall                                     # chỉ báo cáo
+piagent-uninstall --apply                             # gỡ Pi package của platform
+piagent-uninstall --apply --with-addons --with-host   # + add-on và Pi host
+piagent-uninstall --apply --project /path/to/project  # + state trong project
+npm uninstall -g @piagent/platform                    # helper npm-global</code></pre>
+                  </div>
+                  <p>Nó gỡ theo những gì đang đăng ký trong Pi settings chứ không theo những gì bản hiện tại cài, nên package do release cũ đăng ký vẫn ra được.</p>
+                  <div class="callout ok-callout">
+                    <strong>Không bao giờ bị xoá</strong>
+                    <p>Credential, trust, session, todo và <span class="inline-code">.pi/memory/</span> được giữ nguyên ở mọi tổ hợp cờ — đó là dữ liệu của người dùng, không phải state của platform. Các file sinh từ template rồi sửa tiếp như <span class="inline-code">AGENTS.md</span>, <span class="inline-code">.pi/settings.json</span>, <span class="inline-code">project-context.md</span> chỉ được liệt kê để tự quyết. Với <span class="inline-code">.pi/settings.json</span>, chỉ đúng entry trỏ tới platform bị bỏ khỏi <span class="inline-code">packages</span>.</p>
+                  </div>
+                </div>
+              </article>
+
               <article class="step">
                 <div>
                   <h3>Mở repo dự án</h3>
@@ -1178,12 +1206,14 @@ npm run typecheck</code></pre>
 
             <div class="callout">
               <strong>Redaction cần kiểm toán độc lập</strong>
-              <p>Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Dự án công khai <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model và attack-vector map</a>; phạm vi OS/shell rộng hơn, parser fuzzing, third-party audit, signed provenance và LTS vẫn là các mức bảo đảm cao hơn chưa được claim.</p>
+              <p>Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Dự án công khai <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model và attack-vector map</a>; phạm vi OS/shell rộng hơn, parser fuzzing, third-party audit và LTS vẫn là các mức bảo đảm cao hơn chưa được claim. Signed provenance thì đã có: mỗi bản publish lên npm mang attestation ký qua sigstore từ GitHub Actions, buộc tarball về đúng commit và workflow tạo ra nó.</p>
             </div>
 
             <div class="callout">
               <strong>Dependency gate tách hai lớp</strong>
-              <p>Release kiểm toán riêng dependency tree nhỏ của terminal helper và cây exact Pi host + pinned add-on. Gate hiện có 0 high/critical; npm vẫn báo 11 moderate dependency paths thuộc hai advisory upstream: encoded-backslash path traversal trên Windows trong Hono adapter và protobuf parser DoS. Native Windows/WSL2 chưa nằm trong matrix rollout team, nhưng dự án vẫn theo dõi cả hai thay vì gọi runtime là “0 vulnerability”.</p>
+              <p>Release kiểm toán riêng dependency tree nhỏ của terminal helper và cây exact Pi host + pinned add-on. Helper tree hiện sạch hoàn toàn. Cây Pi host có 1 high và 11 moderate, và dự án nói thẳng con số đó thay vì gọi runtime là “0 vulnerability”.</p>
+              <p>Bản high là <span class="inline-code">GHSA-mh99-v99m-4gvg</span> trong <span class="inline-code">brace-expansion</span> — DoS, không leo quyền, không lộ dữ liệu. Repo này không sửa được: Pi host publish kèm <span class="inline-code">npm-shrinkwrap.json</span> ghim version dính lỗi, mà shrinkwrap đã publish thì thắng <span class="inline-code">overrides</span> của consumer. Mọi bản Pi đã phát hành đều dính một advisory brace-expansion, nên pin bản cũ chỉ đổi lỗi này lấy lỗi khác. Vì vậy gate miễn trừ đúng một advisory có tên, kèm lý do ghi trong mã nguồn, và tự đỏ lại khi hết hạn rà soát <span class="inline-code">2026-08-25</span> hoặc ngay khi upstream vá xong. Mọi high/critical khác vẫn chặn.</p>
+              <p>11 moderate còn lại thuộc hai advisory upstream: encoded-backslash path traversal trên Windows trong Hono adapter, và protobuf parser DoS. Native Windows/WSL2 chưa nằm trong matrix rollout team, nhưng dự án vẫn theo dõi cả hai.</p>
             </div>
           </section>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -47,6 +47,7 @@
   "bin": {
     "piagent-setup": "scripts/piagent-cli.mjs",
     "piagent-install": "scripts/piagent-cli.mjs",
+    "piagent-uninstall": "scripts/piagent-cli.mjs",
     "piagent-init": "scripts/piagent-cli.mjs",
     "piagent-doctor": "scripts/piagent-cli.mjs",
     "piagent-benchmark": "scripts/piagent-cli.mjs",
@@ -93,8 +94,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.13.14",
-    "typescript": "^5.8.3"
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
   },
   "workspaces": [
     "packages/*"

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "private": true,
   "license": "MIT",

package/scripts/install-global.sh

@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.0.1 --resolve-tag
+  scripts/install-global.sh --version v1.0.2 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -123,7 +123,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.0.1 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.0.2 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -131,7 +131,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.1 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.2 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;

package/scripts/piagent-cli.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 const scriptByCommand = {
   "piagent-setup": "scripts/setup.sh",
   "piagent-install": "scripts/install-global.sh",
+  "piagent-uninstall": "scripts/uninstall-global.sh",
   "piagent-init": "scripts/init-project.sh",
   "piagent-doctor": "scripts/team-doctor.sh",
   "piagent-benchmark": "scripts/quality-benchmark.sh",

package/scripts/setup.sh

@@ -244,6 +244,20 @@ NODE
     fi
   fi
 
+  # Running from an installed package rather than a checkout. The name and
+  # version on disk are exactly what a teammate resolves from the registry, so
+  # they are a portable source; the install path is not, and project settings
+  # are meant to be committed.
+  if [[ "$PLATFORM_ROOT" == */node_modules/* ]]; then
+    local installed_name installed_version
+    installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
+    installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
+    if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+      printf 'npm:%s@%s\n' "$installed_name" "$installed_version"
+      return
+    fi
+  fi
+
   echo "WARN: No exact package source provided." >&2
   echo "WARN: using local platform path; do not commit project .pi/settings.json with this value for team rollout." >&2
   printf '%s\n' "$PLATFORM_ROOT"

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.0.1 support matrix."
+    note: "This runtime is outside the documented v1.0.2 support matrix."
   };
 }
 

package/scripts/uninstall-global.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Removes what this platform installed, and nothing else.
+#
+# Uninstall is reported before it is performed, for the same reason install is:
+# the two touch shared Pi state that other tools also write to. Anything this
+# script cannot prove it installed is listed for the operator instead of being
+# deleted.
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PI_AGENT_DIR="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
+GLOBAL_SETTINGS="$PI_AGENT_DIR/settings.json"
+
+APPLY=false
+WITH_ADDONS=false
+WITH_HOST=false
+PROJECT_PATH=""
+
+PLATFORM_PACKAGE="@piagent/platform"
+ADDON_PACKAGES=("pi-mcp-adapter" "pi-subagents" "pi-web-access")
+PI_HOST_PACKAGE="@earendil-works/pi-coding-agent"
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  piagent-uninstall [--apply] [--with-addons] [--with-host] [--project <path>]
+
+Removes the Pi package this platform installed from Pi's global settings.
+
+  (default)        Dry run. Reports what would be removed and exits 0.
+  --apply          Perform the removal.
+  --with-addons    Also remove pi-mcp-adapter, pi-subagents, and pi-web-access.
+  --with-host      Also uninstall the global Pi Coding Agent host.
+  --project <path> Also remove this platform's state from a project.
+
+Never removed, at any flag combination: credentials, trust decisions, sessions,
+todos, and project memory. Those are operator data, not platform state.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --apply) APPLY=true; shift ;;
+    --with-addons) WITH_ADDONS=true; shift ;;
+    --with-host) WITH_HOST=true; shift ;;
+    --project)
+      if [[ $# -lt 2 || -z "${2:-}" ]]; then
+        echo "Missing value for --project" >&2
+        exit 2
+      fi
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    -h|--help) usage; exit 0 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+print_cmd() {
+  printf '+'
+  for arg in "$@"; do printf ' %q' "$arg"; done
+  printf '\n'
+}
+
+run_cmd() {
+  print_cmd "$@"
+  if [[ "$APPLY" == true ]]; then
+    "$@"
+  fi
+}
+
+# Reads the package sources Pi has registered, so removal targets what is
+# actually installed rather than what this version happens to install today. An
+# older release registered a different source shape, and it still has to come
+# out.
+platform_sources() {
+  [[ -f "$GLOBAL_SETTINGS" ]] || return 0
+  node --input-type=module - "$GLOBAL_SETTINGS" <<'NODE'
+import fs from "node:fs";
+
+let settings;
+try {
+  settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+} catch {
+  process.exit(0);
+}
+const packages = Array.isArray(settings.packages) ? settings.packages : [];
+// Every shape this platform has ever been installed as: the scoped npm
+// package, the Git source, and a local checkout path.
+const owned = /(@piagent\/platform|[/:]piagent(@|$|#)|Vt-mmm\/piagent|pi-company-platform)/;
+for (const entry of packages) {
+  if (typeof entry === "string" && owned.test(entry)) process.stdout.write(`${entry}\n`);
+}
+NODE
+}
+
+addon_sources() {
+  [[ -f "$GLOBAL_SETTINGS" ]] || return 0
+  node --input-type=module - "$GLOBAL_SETTINGS" "${ADDON_PACKAGES[@]}" <<'NODE'
+import fs from "node:fs";
+
+let settings;
+try {
+  settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+} catch {
+  process.exit(0);
+}
+const names = process.argv.slice(3);
+const packages = Array.isArray(settings.packages) ? settings.packages : [];
+for (const entry of packages) {
+  if (typeof entry !== "string") continue;
+  if (names.some((name) => entry.includes(name))) process.stdout.write(`${entry}\n`);
+}
+NODE
+}
+
+echo "Pi Agent Platform uninstall"
+echo "  mode: $([[ "$APPLY" == true ]] && echo apply || echo "dry run")"
+echo "  settings: $GLOBAL_SETTINGS"
+echo "  addons: $WITH_ADDONS"
+echo "  host: $WITH_HOST"
+[[ -n "$PROJECT_PATH" ]] && echo "  project: $PROJECT_PATH"
+echo
+
+if ! command -v pi >/dev/null 2>&1; then
+  echo "WARN: pi is not on PATH; skipping Pi package removal." >&2
+  echo "WARN: reinstall the host or remove entries from $GLOBAL_SETTINGS by hand." >&2
+else
+  found=false
+  while IFS= read -r source; do
+    [[ -z "$source" ]] && continue
+    found=true
+    echo "Removing platform package:"
+    run_cmd pi remove "$source"
+  done < <(platform_sources)
+  if [[ "$found" == false ]]; then
+    echo "No platform package found in Pi settings; nothing to remove."
+  fi
+
+  if [[ "$WITH_ADDONS" == true ]]; then
+    addon_found=false
+    while IFS= read -r source; do
+      [[ -z "$source" ]] && continue
+      addon_found=true
+      echo "Removing add-on:"
+      run_cmd pi remove "$source"
+    done < <(addon_sources)
+    if [[ "$addon_found" == false ]]; then
+      echo "No pinned add-on found in Pi settings."
+    fi
+    # The MCP baseline and subagent config are shared files that the operator
+    # may have edited after install, so they are reported rather than reset.
+    echo "Left in place, review by hand if no longer wanted:"
+    echo "  $PI_AGENT_DIR/mcp.json"
+    echo "  $PI_AGENT_DIR/extensions/subagent/config.json"
+  fi
+fi
+
+if [[ "$WITH_HOST" == true ]]; then
+  echo
+  if command -v npm >/dev/null 2>&1; then
+    echo "Uninstalling Pi host:"
+    run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+  else
+    echo "WARN: npm is not on PATH; cannot uninstall $PI_HOST_PACKAGE." >&2
+  fi
+fi
+
+if [[ -n "$PROJECT_PATH" ]]; then
+  echo
+  if [[ ! -d "$PROJECT_PATH" ]]; then
+    echo "FAIL: project path does not exist: $PROJECT_PATH" >&2
+    exit 1
+  fi
+  PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+  echo "Project state in $PROJECT_PATH:"
+
+  # Files this platform alone writes and owns.
+  for relative in ".pi/piagent-profile.json" ".pi/piagent-profile.lock.json"; do
+    [[ -e "$PROJECT_PATH/$relative" ]] && run_cmd rm -f "$PROJECT_PATH/$relative"
+  done
+  if [[ -d "$PROJECT_PATH/.pi/piagent-state" ]]; then
+    run_cmd rm -rf "$PROJECT_PATH/.pi/piagent-state"
+  fi
+
+  # settings.json belongs to Pi, not to this platform. Only the package entry
+  # pointing here comes out; everything else the operator configured stays.
+  if [[ -f "$PROJECT_PATH/.pi/settings.json" ]]; then
+    echo "+ drop platform package entry from $PROJECT_PATH/.pi/settings.json"
+    if [[ "$APPLY" == true ]]; then
+      node --input-type=module - "$PROJECT_PATH/.pi/settings.json" <<'NODE'
+import fs from "node:fs";
+
+const target = process.argv[2];
+const settings = JSON.parse(fs.readFileSync(target, "utf8"));
+if (Array.isArray(settings.packages)) {
+  const owned = /(@piagent\/platform|[/:]piagent(@|$|#)|Vt-mmm\/piagent|pi-company-platform)/;
+  const kept = settings.packages.filter((entry) => !(typeof entry === "string" && owned.test(entry)));
+  if (kept.length > 0) settings.packages = kept;
+  else delete settings.packages;
+  fs.writeFileSync(target, `${JSON.stringify(settings, null, 2)}\n`);
+}
+NODE
+    fi
+  fi
+
+  # Written from templates at init, then edited by whoever used the project.
+  # Deleting them would take the operator's work with them.
+  echo "Left in place because they carry project content:"
+  for relative in "AGENTS.md" "REVIEW_GUIDELINES.md" ".mcp.json" ".pi/settings.json" ".pi/mcp.json" \
+    ".pi/project-context.md" ".pi/context-index.json" ".pi/tech-stack.json" ".pi/tech-context" ".pi/memory"; do
+    [[ -e "$PROJECT_PATH/$relative" ]] && echo "  $relative"
+  done
+fi
+
+echo
+if [[ "$APPLY" == true ]]; then
+  echo "Uninstall complete."
+  echo "The npm-global helper is separate and stays until you remove it:"
+  echo "  npm uninstall -g $PLATFORM_PACKAGE"
+else
+  echo "Dry run only. Nothing was removed. Re-run with --apply to perform it."
+fi

package/scripts/verify-local.sh

@@ -148,6 +148,7 @@ required_files=(
   "$ROOT/scripts/verify-vercel-link.mjs"
   "$ROOT/scripts/piagent-cli.mjs"
   "$ROOT/scripts/init-project.sh"
+  "$ROOT/scripts/uninstall-global.sh"
   "$ROOT/scripts/setup.sh"
   "$ROOT/scripts/team-doctor.sh"
   "$ROOT/scripts/link-project.sh"
@@ -179,6 +180,7 @@ required_files=(
   "$ROOT/tests/runtime-advisories.test.mjs"
   "$ROOT/scripts/check-runtime-advisories.mjs"
   "$ROOT/tests/migrate-project-state.test.mjs"
+  "$ROOT/tests/uninstall-global.test.mjs"
   "$ROOT/tests/import-agent-instructions.test.mjs"
   "$ROOT/evals/golden/enforcement-decisions.json"
 )
@@ -305,10 +307,22 @@ for (const [sourceName, versionName, packageName] of pins) {
   }
 }
 NODE
-grep -F 'actions/checkout@11d5960a326750d5838078e36cf38b85af677262' "$ROOT/.github/workflows/verify.yml" "$ROOT/.github/workflows/codeql.yml" >/dev/null
-grep -F 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' "$ROOT/.github/workflows/verify.yml" >/dev/null
-grep -F 'github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81' "$ROOT/.github/workflows/codeql.yml" >/dev/null
-grep -F 'github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81' "$ROOT/.github/workflows/codeql.yml" >/dev/null
+# Each reviewed action revision is asserted by hand so that a swapped action is
+# a verification failure rather than a silent change. A dependency bot updating
+# an action therefore needs the pin here updated in the same change; without a
+# message naming the pin, that failure reads as an unexplained exit.
+require_action_pin() {
+  local pin="$1"
+  shift
+  if ! grep -F "$pin" "$@" >/dev/null; then
+    echo "reviewed GitHub Actions pin $pin is missing from ${*#"$ROOT/"}; update this pin in the same change that bumps the action" >&2
+    exit 1
+  fi
+}
+require_action_pin 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' "$ROOT/.github/workflows/verify.yml" "$ROOT/.github/workflows/codeql.yml"
+require_action_pin 'actions/setup-node@820762786026740c76f36085b0efc47a31fe5020' "$ROOT/.github/workflows/verify.yml"
+require_action_pin 'github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81' "$ROOT/.github/workflows/codeql.yml"
+require_action_pin 'github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81' "$ROOT/.github/workflows/codeql.yml"
 grep -F 'git cat-file -t "refs/tags/$RELEASE_TAG"' "$ROOT/.github/workflows/verify.yml" >/dev/null
 if grep -R -E '^[[:space:]]*uses:[[:space:]]+[^@[:space:]]+@(main|master|v[0-9]+([.][0-9]+)*)[[:space:]]*(#.*)?$' "$ROOT/.github/workflows" >/dev/null; then
   echo "GitHub Actions workflow contains a mutable action reference" >&2
@@ -465,6 +479,7 @@ bash -n "$ROOT/scripts/configure-mcp.sh"
 bash -n "$ROOT/scripts/configure-subagents.sh"
 bash -n "$ROOT/scripts/install-global.sh"
 bash -n "$ROOT/scripts/init-project.sh"
+bash -n "$ROOT/scripts/uninstall-global.sh"
 bash -n "$ROOT/scripts/setup.sh"
 if [[ "$OFFLINE" == true || "${PIAGENT_VERIFY_OFFLINE:-}" == "1" || "${CI:-}" == "true" ]]; then
   echo "WARN: skipping local Pi model catalog check in offline/CI mode" >&2