@piagent/platform 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.4 - 2026-07-30
+
+### Changed
+
+- `piagent-update` remains a global machine update first; optional `--project <path>` now runs a post-update legacy project migration and strict-share doctor when a maintainer wants that extra check.
+
+- Documented the global `npm exec --package @piagent/platform@X.Y.Z -- piagent-update ...` bootstrap command for machines that do not have the global `piagent-update` helper yet.
+
+- `piagent-update` now falls back to a user-writable npm global prefix when the default prefix is locked by the OS, avoiding `/usr/local/lib/node_modules` permission failures during team rollout.
+
 ## v1.2.3 - 2026-07-30
 
 ### Added

package/README.md

@@ -290,7 +290,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.2.3` 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.2.4` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -464,12 +464,15 @@ 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.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.2.3` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.3` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.4` | 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. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
-| `piagent-update` | Full update một lệnh: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. Thêm `--project <path>` để chạy doctor sau. |
+| `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
 | `piagent-update --version X.Y.Z` | Update tới đúng một release thay vì latest; dùng cho rollout theo lô hoặc rollback. |
+| `piagent-update --project <path>` | Bước phụ sau global update: migrate project cũ nếu có rồi chạy doctor strict-share cho project đó. |
+| `piagent-update --npm-prefix ~/.pi/npm-global` | Ép updater cài host/helper vào npm global prefix của user; hữu ích khi `/usr/local/lib/node_modules` không ghi được. |
+| `npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force` | Bootstrap/update global cho máy chưa có `piagent-update`; chạy từ Terminal, không cần mở Pi. |
 | `PIAGENT_NO_UPDATE_CHECK=1` | Tắt notice "có bản mới" ở đầu session Pi. Mặc định bật, hỏi registry nhiều nhất một lần mỗi 24 giờ ở tiến trình nền. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Sequence thủ công tương đương. Thứ tự bắt buộc: `piagent-install` fail nếu Pi host lệch bản pin và không tự cài host. Version pin của từng release nằm trong [release/install policy](release-install-policy.md). |
 | 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. |

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.2.3` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.4` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.3` |
+| Registry distribution | `npm:@piagent/platform@1.2.4` |
 | 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.2.3` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.4` | 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.2.3
+pi install git:github.com/Vt-mmm/piagent@v1.2.4
 ```
 
 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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.3` 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.2.3`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.4` 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.2.4`.
 
 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).
 
@@ -120,7 +120,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.2.3 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.4 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -189,13 +189,34 @@ Files không commit:
 
 [Release/install policy](release-install-policy.md) là checklist canonical duy nhất. Production docs chỉ được promote sau khi tag đã tồn tại và stable dry-run resolve đúng commit SHA.
 
-Full platform update phải đồng bộ Pi host, npm-global helper và Pi package:
+Full platform update phải đồng bộ Pi host, npm-global helper và Pi package cho cả máy:
+
+```bash
+piagent-update --version X.Y.Z
+```
+
+Máy chưa có helper dùng bootstrap all-in-one:
+
+```bash
+npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
+```
+
+Máy bị khóa npm global ở `/usr/local` không cần `sudo`: updater sẽ dùng prefix user-local `~/.pi/npm-global` hoặc maintainer có thể truyền `--npm-prefix <path>`.
+
+Project migration/doctor là bước kiểm tra sau global update, chỉ chạy cho repo cần xác minh:
+
+```bash
+piagent-update --version X.Y.Z --project /path/to/project
+```
+
+Sequence thủ công tương đương:
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
 npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
+piagent-migrate /path/to/project --apply --remove-old
 piagent-doctor /path/to/project --strict-share
 ```
 

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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 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.2.3`. 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.2.4`. 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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,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.2.3 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.4 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -894,8 +894,8 @@ 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.2.3` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.3` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.4` | 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. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | 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. |
@@ -1002,7 +1002,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.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 command -v piagent-install
 ```
 

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.82.0`. 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.2.3 | Rollout guidance |
+| Surface | Status for v1.2.4 | 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.2.3` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.4` | 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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 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.2.3 (helper package version)
-tag: v1.2.3
+currentRelease: v1.2.4 (helper package version)
+tag: v1.2.4
 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.2.3
+pi install git:github.com/Vt-mmm/piagent@v1.2.4
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -91,11 +91,27 @@ Direct `pi install` does not create `piagent-*` commands on `PATH`.
 ```bash
 piagent-update --check
 piagent-update --dry-run
-piagent-update --project /path/to/project
+piagent-update --version X.Y.Z
 ```
 
 It resolves the target helper version and, from that version's published metadata, the exact Pi host that version pins — both before installing anything, so `--check` and `--dry-run` describe a real run. It then installs the host, replaces the helper, verifies that the version now on disk is the one it asked for, and only then runs the new helper's installer for the Pi package. `--version X.Y.Z` targets an exact release instead of latest, `--no-host` and `--no-package` narrow the run, and anything after `--` is passed to `piagent-install`.
 
+Project migration and doctor are post-update checks, not the update scope. Run them only for the project being verified:
+
+```bash
+piagent-update --version X.Y.Z --project /path/to/project
+```
+
+With `--project`, the updater migrates legacy project state if needed and runs `piagent-doctor --strict-share`; use `--no-migrate` only when debugging a migration.
+
+If the machine's default npm global prefix is locked by the OS, for example `/usr/local/lib/node_modules`, the updater uses `~/.pi/npm-global` for this rollout and prints the `PATH` line to add later. Do not run project update/doctor as root, because that can leave project files owned by root. Maintainers can force a specific prefix with `--npm-prefix <path>`.
+
+For a fresh machine that does not have `piagent-update` yet, bootstrap the same all-in-one flow without opening Pi:
+
+```bash
+npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
+```
+
 Running it from a git checkout is refused rather than replacing that checkout's commands with a published build; update a checkout with `git pull` and `install-global.sh --local`.
 
 The same sequence by hand, which must keep this order because `piagent-install` fails against a host that does not match the version it pins and does not install one itself:

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.2.3, 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.2.4, 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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable
 cd /path/to/project
 pi
@@ -43,7 +43,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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.3
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -68,10 +68,26 @@ Một lệnh, đúng thứ tự, cho cả ba thành phần:
 
 ```bash
 piagent-update --check
-piagent-update --project /path/to/project
+piagent-update --version X.Y.Z
 ```
 
-`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.2.3`.
+Chạy từ Terminal, không cần mở Pi và không cần đứng trong project. Đây là update global cho cả máy: Pi host, npm-global helper, và Pi package.
+
+Khi cần kiểm tra một project sau rollout, chạy riêng:
+
+```bash
+piagent-update --version X.Y.Z --project /path/to/project
+```
+
+`--project` là bước phụ: tự migrate layout cũ nếu có rồi chạy doctor strict-share. `--check` chỉ báo version, không đụng gì.
+
+Nếu npm global mặc định của máy bị khóa quyền ở `/usr/local`, updater tự chuyển sang `~/.pi/npm-global` cho user hiện tại và in dòng `PATH` cần thêm. Không chạy doctor bằng `sudo`.
+
+Máy mới chưa có `piagent-update` dùng một dòng bootstrap này:
+
+```bash
+npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
+```
 
 Không cần ai nhớ đi kiểm tra: khi có release mới, Pi tự báo ngay ở dòng notice lúc mở session, kèm luôn lệnh chạy.
 

package/docs-site/architecture.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/commands.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/index.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/mcp-approval.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/mcp-auth.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/mcp-servers.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/mcp.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/permissions.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/profiles.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/quickstart.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/runtime.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/scope.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/security.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/team.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/docs-site/workflows.html

@@ -27,7 +27,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.3 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.4 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" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/package.json

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

package/scripts/update-global.mjs

@@ -17,6 +17,7 @@
 // it asked for.
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -39,13 +40,18 @@ Options:
   --dry-run               Print every command that would run, change nothing
   --version <x.y.z>       Update to an exact helper version instead of latest
   --force                 Reinstall even when already on the target version
-  --project <path>        Run the team doctor against this project afterwards
+  --project <path>        Optional: after the global update, migrate and doctor this project
   --no-host               Do not touch the Pi host
   --no-package            Do not reinstall the Pi package
+  --no-migrate            With --project, skip project state migration
+  --npm-prefix <path>     Use this npm global prefix for host/helper installs
   -h, --help              Show this help
 
 Anything after -- is passed through to piagent-install, for example:
   piagent-update -- --no-mcp
+
+Bootstrap a machine that does not have piagent-update yet:
+  npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
 `;
 }
 
@@ -81,6 +87,8 @@ function parseArguments(argv) {
     project: undefined,
     host: true,
     package: true,
+    migrate: true,
+    npmPrefix: undefined,
     passthrough: []
   };
 
@@ -111,6 +119,15 @@ function parseArguments(argv) {
       case "--no-package":
         options.package = false;
         break;
+      case "--no-migrate":
+        options.migrate = false;
+        break;
+      case "--npm-prefix": {
+        const value = argv[index += 1];
+        if (!value) fail("--npm-prefix needs a path", EXIT_USAGE);
+        options.npmPrefix = value;
+        break;
+      }
       case "--version": {
         const value = normalizeVersion(argv[index += 1]);
         if (!isReleaseVersion(value)) fail(`--version needs an exact release such as 1.1.4, got ${argv[index] ?? "nothing"}`, EXIT_USAGE);
@@ -140,6 +157,167 @@ function run(command, args, { capture = false } = {}) {
   return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 
+function expandHome(value) {
+  if (value === "~") return os.homedir();
+  if (value?.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function configuredNpmPrefix() {
+  const result = run("npm", ["config", "get", "prefix"], { capture: true });
+  if (!result.ok) return undefined;
+  const prefix = result.stdout.trim();
+  return prefix && prefix !== "undefined" && prefix !== "null" ? path.resolve(expandHome(prefix)) : undefined;
+}
+
+function fallbackNpmRoot(prefix) {
+  return process.platform === "win32"
+    ? path.join(prefix, "node_modules")
+    : path.join(prefix, "lib", "node_modules");
+}
+
+function npmRoot(prefix) {
+  const args = ["root", "-g"];
+  if (prefix) args.push("--prefix", prefix);
+  const result = run("npm", args, { capture: true });
+  if (result.ok && result.stdout.trim()) return path.resolve(expandHome(result.stdout.trim()));
+  return prefix ? fallbackNpmRoot(prefix) : undefined;
+}
+
+function nearestExistingPath(target) {
+  let current = target;
+  while (current && !fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return current || undefined;
+}
+
+function canWriteOrCreate(target) {
+  const nearest = nearestExistingPath(target);
+  if (!nearest) return false;
+  try {
+    fs.accessSync(nearest, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function userNpmPrefix() {
+  return path.join(os.homedir(), ".pi", "npm-global");
+}
+
+function binForPrefix(prefix) {
+  return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function prependPath(directory) {
+  process.env.PATH = `${directory}${path.delimiter}${process.env.PATH ?? ""}`;
+}
+
+function resolveNpmInstallTarget(options, needsGlobalInstall) {
+  const explicitPrefix = options.npmPrefix ? path.resolve(expandHome(options.npmPrefix)) : undefined;
+  if (explicitPrefix) {
+    if (!options.dryRun) fs.mkdirSync(explicitPrefix, { recursive: true });
+    return {
+      prefix: explicitPrefix,
+      root: npmRoot(explicitPrefix),
+      bin: binForPrefix(explicitPrefix),
+      reason: "explicit"
+    };
+  }
+
+  const defaultPrefix = configuredNpmPrefix();
+  const defaultRoot = npmRoot(defaultPrefix);
+  if (!needsGlobalInstall || (defaultRoot && canWriteOrCreate(defaultRoot))) {
+    return { prefix: undefined, root: defaultRoot, bin: undefined, reason: "default" };
+  }
+
+  const prefix = userNpmPrefix();
+  if (!options.dryRun) fs.mkdirSync(prefix, { recursive: true });
+  return {
+    prefix,
+    root: npmRoot(prefix),
+    bin: binForPrefix(prefix),
+    reason: "user-prefix",
+    blockedRoot: defaultRoot
+  };
+}
+
+function npmInstallArgs(specifier, npmTarget) {
+  const args = ["install", "-g", "--ignore-scripts"];
+  if (npmTarget.prefix) args.push("--prefix", npmTarget.prefix);
+  args.push(specifier);
+  return args;
+}
+
+function helperRootFromNpmTarget(npmTarget) {
+  return npmTarget.root ? path.join(npmTarget.root, "@piagent", "platform") : undefined;
+}
+
+function helperVersionAt(root) {
+  return root ? readJson(path.join(root, "package.json"))?.version : undefined;
+}
+
+function resolveInstalledHelperRoot(targetHelper, npmTarget) {
+  const npmHelperRoot = helperRootFromNpmTarget(npmTarget);
+  if (helperVersionAt(npmHelperRoot) === targetHelper) return npmHelperRoot;
+  if (helperVersionAt(platformRoot) === targetHelper) return platformRoot;
+  const checked = [];
+  for (const root of [npmHelperRoot, platformRoot]) {
+    if (!root || checked.some((entry) => entry.root === root)) continue;
+    checked.push({ root, version: helperVersionAt(root) ?? "nothing" });
+  }
+  const details = checked.map((entry) => `${entry.root} reports ${entry.version}`).join("; ");
+  fail(`installed ${HELPER_PACKAGE}@${targetHelper}, but ${details || "the helper paths did not report that version"}. `
+    + "The Pi package was left untouched; rerun once the helper is correct.");
+}
+
+function parseJsonOutput(result, label) {
+  try {
+    return JSON.parse(result.stdout.trim() || "{}");
+  } catch {
+    fail(`${label} did not return valid JSON:\n${result.stdout.trim()}`);
+  }
+}
+
+function summarizeMigration(report, dryRun) {
+  const renamed = report.renamed?.length ?? 0;
+  const removed = report.removedOld?.length ?? 0;
+  const rewrote = report.rewrote?.length ?? report.wouldRewrite?.length ?? 0;
+  const wouldRename = report.wouldRename?.length ?? 0;
+  const alreadyMigrated = report.alreadyMigrated?.length ?? 0;
+
+  if (dryRun) {
+    const planned = wouldRename + rewrote + alreadyMigrated;
+    return planned > 0
+      ? `project migration: would update legacy layout (${wouldRename} rename, ${rewrote} rewrite, ${alreadyMigrated} already copied)`
+      : "project migration: already current";
+  }
+  if (report.migrated === false) return "project migration: already current";
+  return `project migration: applied (${renamed} rename, ${rewrote} rewrite, ${removed} old path removed)`;
+}
+
+function runProjectMigration(project, options, activePlatformRoot) {
+  const migrator = path.join(activePlatformRoot, "scripts/migrate-project-state.mjs");
+  if (!options.dryRun && !fs.existsSync(migrator)) {
+    fail(`the updated helper has no project migrator at ${migrator}`);
+  }
+  const args = options.dryRun
+    ? [migrator, project]
+    : [migrator, project, "--apply", "--remove-old"];
+  describeStep(options.dryRun, process.execPath, args);
+  const result = run(process.execPath, args, { capture: true });
+  if (!result.ok) fail(`project migration failed:\n${result.stderr.trim() || result.stdout.trim()}`);
+  const report = parseJsonOutput(result, "project migration");
+  if ((report.skipped?.length ?? 0) > 0) {
+    fail(`project migration skipped protected entries: ${report.skipped.map((entry) => `${entry.path} (${entry.reason})`).join(", ")}`);
+  }
+  console.log(`  ${summarizeMigration(report, options.dryRun)}`);
+}
+
 function npmView(specifier, field) {
   const result = run("npm", ["view", specifier, field, "--json"], { capture: true });
   if (!result.ok) return undefined;
@@ -196,6 +374,9 @@ function main() {
   console.log(`  helper:  ${currentHelper} -> ${targetHelper}${helperNeedsChange ? "" : " (already current)"}`);
   console.log(`  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
   console.log(`  package: reinstalled from v${targetHelper} as a resolved commit${options.package ? "" : " (skipped)"}`);
+  if (options.project) {
+    console.log(`  project: ${path.resolve(options.project)} (${options.migrate ? "migrate + doctor" : "doctor only"})`);
+  }
 
   if (options.check) {
     const pending = [helperNeedsChange && "helper", hostNeedsChange && "host"].filter(Boolean);
@@ -203,7 +384,7 @@ function main() {
     return;
   }
 
-  if (!helperNeedsChange && !hostNeedsChange && !options.package) {
+  if (!helperNeedsChange && !hostNeedsChange && !options.package && !options.project) {
     console.log("\nNothing to do.");
     return;
   }
@@ -215,33 +396,38 @@ function main() {
       + `  bash ${path.join(platformRoot, "scripts/install-global.sh")} --local`);
   }
 
+  let activePlatformRoot = platformRoot;
+  const npmTarget = resolveNpmInstallTarget(options, hostNeedsChange || helperNeedsChange);
+  if (npmTarget.bin) prependPath(npmTarget.bin);
+  if (npmTarget.reason === "user-prefix") {
+    console.log(`  npm:     default global root is not writable (${npmTarget.blockedRoot ?? "unknown"}); using ${npmTarget.prefix}`);
+  } else if (npmTarget.reason === "explicit") {
+    console.log(`  npm:     using explicit global prefix ${npmTarget.prefix}`);
+  }
+
   // Host first: piagent-install refuses to run against a host that does not match
   // the version its package.json pins, so a helper installed ahead of the host
   // would fail on its very next step.
   if (hostNeedsChange) {
-    const args = ["install", "-g", "--ignore-scripts", `${HOST_PACKAGE}@${targetHost}`];
+    const args = npmInstallArgs(`${HOST_PACKAGE}@${targetHost}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);
   }
 
   if (helperNeedsChange) {
-    const args = ["install", "-g", "--ignore-scripts", `${HELPER_PACKAGE}@${targetHelper}`];
+    const args = npmInstallArgs(`${HELPER_PACKAGE}@${targetHelper}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun) {
       if (!run("npm", args).ok) fail(`could not install ${HELPER_PACKAGE}@${targetHelper}`);
       // The helper has just replaced itself on disk. Everything after this point
       // runs the newly installed scripts, so confirm they are the ones asked for
       // rather than trusting that npm did what it said.
-      const landed = readJson(path.join(platformRoot, "package.json"))?.version;
-      if (landed !== targetHelper) {
-        fail(`installed ${HELPER_PACKAGE}@${targetHelper} but ${platformRoot} reports ${landed ?? "nothing"}. `
-          + "The Pi package was left untouched; rerun once the helper is correct.");
-      }
+      activePlatformRoot = resolveInstalledHelperRoot(targetHelper, npmTarget);
     }
   }
 
   if (options.package) {
-    const installer = path.join(platformRoot, "scripts/install-global.sh");
+    const installer = path.join(activePlatformRoot, "scripts/install-global.sh");
     if (!options.dryRun && !fs.existsSync(installer)) {
       fail(`the updated helper has no installer at ${installer}`);
     }
@@ -251,12 +437,22 @@ function main() {
   }
 
   if (options.project) {
-    const doctor = path.join(platformRoot, "scripts/team-doctor.sh");
+    if (options.migrate) {
+      runProjectMigration(options.project, options, activePlatformRoot);
+    } else {
+      console.log("  project migration: skipped");
+    }
+    const doctor = path.join(activePlatformRoot, "scripts/team-doctor.sh");
     const args = [doctor, options.project, "--strict-share"];
     describeStep(options.dryRun, "bash", args);
     if (!options.dryRun && !run("bash", args).ok) fail("the team doctor reported a problem");
   }
 
+  if (npmTarget.reason === "user-prefix") {
+    console.log(`\nPATH note: add this once if your shell cannot find piagent-* commands later:`);
+    console.log(`  export PATH="${npmTarget.bin}:$PATH"`);
+  }
+
   console.log(options.dryRun
     ? `\nDRY RUN: nothing was installed. Rerun without --dry-run to apply v${targetHelper}.`
     : `\nPASS: updated to v${targetHelper}.`);