@piagent/platform 1.2.2 → 1.2.4

package/docs/project-onboarding.md

@@ -2,7 +2,7 @@
 
 ## Mục tiêu
 
-Lần đầu gắn một project vào Pi Agent Platform, không nên nhảy thẳng vào `/task`.
+Lần đầu gắn một project vào Pi Agent Platform, không nên nhảy thẳng vào `/workflow task`.
 
 Luồng chuẩn là:
 
@@ -11,10 +11,11 @@ cd /path/to/project
 pi
 /login
 <select provider/model>
-/onboard-project
+/onboard
+/onboard run
 ```
 
-Sau khi `/onboard-project` chạy xong, project có file:
+`/onboard` mở menu/status runtime. Sau khi `/onboard run` chạy xong, project có file:
 
 ```text
 .pi/piagent-profile.json
@@ -27,7 +28,7 @@ Sau khi `/onboard-project` chạy xong, project có file:
 .pi/memory/MEMORY.md
 ```
 
-`/onboard-project` là nơi profile và tech stack được chọn. Ưu tiên select-style flow:
+`/onboard run` là nơi profile và tech stack được chọn trong onboarding workflow. Ưu tiên select-style flow:
 
 ```text
 /profile setup
@@ -40,7 +41,7 @@ Nếu Pi host chưa có native select, command trả card compact và lệnh det
 
 `.pi/context-index.json` là compact advisory index dạng node/edge/citation cho profile, tech stack, verify command, docs, risk, memory pointer và task handoff đã được duyệt. Nó giúp agent tìm đúng điểm vào repo nhanh hơn, nhưng không phải source of truth hoặc security boundary.
 
-Context index là Pi runtime state. Không đọc/ghi raw file này trong workflow thường ngày; dùng `/context-index`, `piagent_context_index_status`, `piagent_context_index_search`, `/onboard-project` hoặc `piagent_context_index_record` để runtime có thể kiểm soát path và sanitize dữ liệu advisory trước khi đưa vào model.
+Context index là Pi runtime state. Không đọc/ghi raw file này trong workflow thường ngày; dùng `/context`, `piagent_context_index_status`, `piagent_context_index_search`, `/onboard run` hoặc `piagent_context_index_record` để runtime có thể kiểm soát path và sanitize dữ liệu advisory trước khi đưa vào model.
 
 Memory markdown là local/private mặc định và bị ignore bởi `.pi/.gitignore`. Chỉ commit memory nếu team quyết định opt-in sau khi review/redact.
 
@@ -50,7 +51,7 @@ Memory markdown là local/private mặc định và bị ignore bởi `.pi/.giti
 
 Bash setup chỉ biết tạo template và detect marker. Nó không có model reasoning, không biết project purpose, module ownership, domain rule, hay risk boundary.
 
-`/onboard-project` phải chạy sau login/model selection để chính model sẽ dùng cho task đọc qua project, chọn/gợi ý profile, và tạo snapshot.
+`/onboard run` phải chạy sau login/model selection để chính model sẽ dùng cho task đọc qua project, chọn/gợi ý profile, và tạo snapshot.
 
 ## Profile selection
 
@@ -108,8 +109,8 @@ Mục tiêu là hiểu cấu trúc và policy, không nhồi full repo vào cont
 `piagent_project_onboarding_record` sẽ tự ghi thêm `.pi/context-index.json` khi tool có sẵn. Nếu cần kiểm tra nhanh, dùng:
 
 ```text
-/context-index
-/context-index search <keyword>
+/context index
+/context search <keyword>
 ```
 
 ## Khi nào regenerate
@@ -117,7 +118,7 @@ Mục tiêu là hiểu cấu trúc và policy, không nhồi full repo vào cont
 Chạy lại:
 
 ```text
-/onboard-project
+/onboard run
 ```
 
 khi có thay đổi lớn:
@@ -128,8 +129,8 @@ khi có thay đổi lớn:
 - API/schema/migration/auth/provider policy đổi;
 - project ownership hoặc domain rule đổi.
 
-## Relationship với `/task`
+## Relationship với `/workflow task`
 
-`/task` sẽ yêu cầu đọc `.pi/project-context.md`. Nếu file còn trạng thái `Generated: not yet`, agent phải dừng và yêu cầu chạy `/onboard-project` trước.
+`/workflow task` sẽ yêu cầu đọc `.pi/project-context.md`. Nếu file còn trạng thái `Generated: not yet`, agent phải dừng và yêu cầu chạy `/onboard run` trước.
 
 Đây là điểm khác với CLI thuần: context bootstrap trở thành một bước có artifact có thể review và tái dùng. `.pi/project-context.md` và `.pi/context-index.json` có thể commit cho team sau khi review; memory markdown thì private-by-default.

package/docs/publishing-for-teams.md

@@ -54,7 +54,7 @@ pi install /path/to/piagent
 - `1.1.9`: notice update hiện đúng trên bản cài bằng `pi install git:` — bản cài nhận diện theo vị trí thư mục, không theo `.git`.
 - `1.2.0`: `piagent-mcp` quản lý server đầy đủ, server do repo mang theo phải được duyệt mới dùng được, và `/piagent-mcp` là command trong session chứ không phải nhờ model chạy bash.
 - `1.2.1`: approval gate thật sự phủ direct tool và server đến qua `imports` — hai đường vòng mà bản `1.2.0` để hở; kèm một loạt fix về containment khi vendor, độ sâu shell guard, và credential trong URL.
-- `1.2.2`: tool output dài được compact vào preview trong Pi và capture local cho Agent Watch/report; thêm `/setname` và `/piagent-logs` cho session naming và log audit gọn.
+- `1.2.2`: tool output dài được compact vào preview trong Pi và capture local cho Agent Watch/report; thêm `/setname` và `/logs` cho session naming và log audit gọn.
 
 ## Không publish
 
@@ -70,7 +70,7 @@ pi install /path/to/piagent
 2. Install the pinned terminal helper and matching Pi package.
 3. Login OAuth provider.
 4. Run `pi` in the target project.
-5. Run `/onboard-project`.
+5. Run `/onboard`.
 6. Choose/apply a profile inside Pi.
 
 Chi tiết: `docs/team-onboarding.md` và `docs/distribution-standard.md`.

package/docs/quickstart-vietnamese.md

@@ -66,17 +66,18 @@ Sau khi login và chọn model intended cho project understanding:
 ```text
 /model          # hoặc Ctrl+L để chọn model bằng selector của Pi
 /scoped-models  # optional, chỉnh danh sách Ctrl+P cycle
-/piagent-commands
+/commands
 /mcp            # kiểm tra MCP adapter/server
 /subagents-doctor  # health check subagent setup
-/onboard-project
-/context-index
-/memory-policy
+/onboard
+/onboard run
+/context index
+/memory
 ```
 
 `Ctrl+L` mở model selector, `Ctrl+P` đổi model trong scope, `Shift+Tab` đổi mức thinking. `piagent-setup` đã config sẵn `enabledModels`, MCP baseline preset `core`, và subagents preset `safe` — muốn xem hoặc đổi thì có [model-options.md](model-options.md), [mcp-and-tools.md](mcp-and-tools.md), [subagents-and-multiagent.md](subagents-and-multiagent.md).
 
-`/onboard-project` yêu cầu model đọc qua project theo phạm vi có kiểm soát, rồi ghi:
+`/onboard` yêu cầu model đọc qua project theo phạm vi có kiểm soát, rồi ghi:
 
 ```text
 .pi/piagent-profile.json
@@ -98,9 +99,9 @@ Nếu chưa có profile/tech stack, dùng select-style flow để tránh agent t
 
 `web-frontend` chọn FE + database optional; `backend-api` chọn BE + database optional; `fullstack` chọn frontend, backend và database. Nếu Pi host chưa có native select, command sẽ trả card ngắn và lệnh deterministic `/profile tech apply ...`.
 
-`.pi/project-context.md` là snapshot context cho task sau. `.pi/context-index.json` là bản đồ node/edge/citation compact để tìm đúng điểm vào repo; vẫn phải đọc source hiện tại trước khi sửa. Không đọc/ghi raw file index trong task thường ngày; dùng `/context-index`, `/onboard-project` hoặc `piagent_context_index_record` để runtime sanitize dữ liệu advisory. Nếu snapshot còn `Generated: not yet` hoặc `/context-index` báo pending/stale, agent phải dừng trước task lớn và yêu cầu chạy `/onboard-project`.
+`.pi/project-context.md` là snapshot context cho task sau. `.pi/context-index.json` là bản đồ node/edge/citation compact để tìm đúng điểm vào repo; vẫn phải đọc source hiện tại trước khi sửa. Không đọc/ghi raw file index trong task thường ngày; dùng `/context`, `/onboard run` hoặc `piagent_context_index_record` để runtime sanitize dữ liệu advisory. Nếu snapshot còn `Generated: not yet` hoặc `/context index` báo pending/stale, agent phải dừng trước task lớn và yêu cầu chạy `/onboard run`.
 
-`/memory-policy` kiểm tra chính sách memory của project. Mặc định memory là explicit-only: chỉ ghi khi user yêu cầu rõ “remember this”, không tự học transcript nền.
+`/memory` kiểm tra chính sách memory của project. `/memory-policy` vẫn là alias. Mặc định memory là explicit-only: chỉ ghi khi user yêu cầu rõ “remember this”, không tự học transcript nền.
 
 ## Bước 4 — init thêm project khác
 
@@ -122,32 +123,33 @@ cd <project>
 pi --name "ABC-123 Short task name"
 ```
 
-Rồi mô tả việc cần làm bằng tiếng Việt hoặc tiếng Anh. Nếu quên đặt tên lúc mở Pi, gõ `/setname ABC-123 Short task name` trước khi làm tiếp; Agent Watch sẽ dùng tên session này trong report. Không cần paste checklist — input guard tự collapse boilerplate, và `/task` tự cân nhắc gọi scout/planner/reviewer khi task đủ lớn.
+Rồi mô tả việc cần làm bằng tiếng Việt hoặc tiếng Anh. Nếu quên đặt tên lúc mở Pi, gõ `/name ABC-123 Short task name` hoặc alias ngắn `/setname ABC-123 Short task name` trước khi làm tiếp; Agent Watch sẽ dùng tên session này trong report. Không cần paste checklist — input guard tự collapse boilerplate, và `/workflow task` tự cân nhắc gọi scout/planner/reviewer khi task đủ lớn.
 
 Muốn chạy nhiều agent song song thì gõ `herdr` thay vì `pi`, rồi mở mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal/session, không phải security boundary — gate vẫn nằm ở Pi extension và OAuth vẫn `/login` trong Pi. Chi tiết: [herdr-workflow.md](herdr-workflow.md).
 
 | Gõ | Khi nào |
 |---|---|
-| `/discuss <ý tưởng>` | Requirement chưa rõ, muốn hỏi lại trước. |
-| `/task <việc>` | Đã rõ, làm luôn. |
-| `/scout <việc>` | Chỉ đọc, không sửa — map payment/auth/BE contract. |
-| `/plan <mục tiêu>` | Muốn có plan trước khi đụng code. |
-| `/review current diff` | Review việc vừa làm. |
-| `/setname <task/session name>` | Đặt/đổi tên session để resume và report dễ đối chiếu. |
-| `/piagent-logs` | Xem các capture khi test/build output quá dài và Pi chỉ hiện preview. |
-| `/be-to-fe <việc>` | Backend read-only, làm FE. |
-| `/commit <message>` | Commit local có kiểm soát, không push. |
-| `/pr <title>` | Tạo PR, hỏi xác nhận trước khi push. |
-| `/fresh-task`, `/fresh-scout`, `/fresh-be-to-fe` | Session đang nặng hoặc tràn context. |
-
-`/piagent-commands` liệt kê hết. Giải thích từng lệnh: [command-reference-vietnamese.md](command-reference-vietnamese.md). Các workflow ép shape rõ (`/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`): [subagents-and-multiagent.md](subagents-and-multiagent.md). Runtime gate tools và cách agent tự dùng chúng: [operator-manual-vietnamese.md](operator-manual-vietnamese.md).
+| `/workflow` | Mở menu chọn task/scout/review/git/onboard. |
+| `/workflow discuss <ý tưởng>` | Requirement chưa rõ, muốn hỏi lại trước. |
+| `/workflow task <việc>` | Đã rõ, làm luôn. |
+| `/workflow scout <việc>` | Chỉ đọc, không sửa — map payment/auth/BE contract. |
+| `/workflow plan <mục tiêu>` | Muốn có plan trước khi đụng code. |
+| `/workflow review current diff` | Review việc vừa làm. |
+| `/name <task/session name>` | Đặt/đổi tên session để resume và report dễ đối chiếu. |
+| `/usage logs` | Xem các capture khi test/build output quá dài và Pi chỉ hiện preview. |
+| `/workflow be-to-fe <việc>` | Backend read-only, làm FE. |
+| `/workflow commit <message>` | Commit local có kiểm soát, không push. |
+| `/workflow pr <title>` | Tạo PR, hỏi xác nhận trước khi push. |
+| `/fresh task|scout|be-to-fe <việc>` | Session đang nặng hoặc tràn context. |
+
+`/commands` liệt kê hết. Các alias cũ như `/task`, `/scout`, `/be-to-fe`, `/fresh-task`, `/context-index`, `/logs` vẫn chạy nhưng không còn là đường onboard chính. Giải thích từng lệnh: [command-reference-vietnamese.md](command-reference-vietnamese.md). Các workflow ép shape rõ (`/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`): [subagents-and-multiagent.md](subagents-and-multiagent.md). Runtime gate tools và cách agent tự dùng chúng: [operator-manual-vietnamese.md](operator-manual-vietnamese.md).
 
 ## Việc user vẫn phải làm thủ công
 
 - Login OAuth lần đầu trong browser.
 - Chọn provider/model intended cho project.
-- Chạy `/onboard-project` lần đầu để tạo `.pi/project-context.md` và `.pi/context-index.json`.
-- Chạy `/memory-policy` nếu muốn kiểm tra hoặc dùng project memory.
+- Chạy `/onboard run` lần đầu để tạo `.pi/project-context.md` và `.pi/context-index.json`.
+- Chạy `/memory` nếu muốn kiểm tra hoặc dùng project memory.
 - Approve project trust nếu Pi hỏi. Sau khi hiểu rõ repo, có thể dùng `piagent-auto` hoặc Pi native `--approve` cho từng lần chạy.
 - Approve khi extension guard hỏi destructive/high-risk action.
 

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.2 | 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.2` | 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.2
+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.2 (helper package version)
-tag: v1.2.2
+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.2
+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/runtime-harness-standard.md

@@ -24,7 +24,7 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 |---|---|---|
 | Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
 | Intake | `piagent_task_start` | Mỗi task có scope, output, acceptance criteria trước khi edit. |
-| Context rules | `/onboard-project`, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
+| Context rules | `/onboard run`, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
 | Test matrix | `verifyCommands` + observed verify evidence | DONE phải có exact verify command thực chạy qua Pi bash hoặc `N/A` rõ lý do. |
 | Trace | `piagent_trace_record`, `.pi/piagent-state/traces.jsonl`, session entry | Có audit trail cho task. |
 | Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
@@ -43,12 +43,12 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 
 ## Workflow prompts
 
-- `/platform-improve`: update package/platform behavior.
-- `/be-to-fe`: scout backend/spec read-only, create contract snapshot, implement frontend only.
-- `/task`: governed implementation lifecycle.
-- `/plan`: create implementation plan.
-- `/discuss`: clarify before work.
-- `/review`: review diff/source with evidence.
+- `/workflow platform-improve`: update package/platform behavior.
+- `/workflow be-to-fe`: scout backend/spec read-only, create contract snapshot, implement frontend only.
+- `/workflow task`: governed implementation lifecycle.
+- `/workflow plan`: create implementation plan.
+- `/workflow discuss`: clarify before work.
+- `/workflow review`: review diff/source with evidence.
 
 ## Task lifecycle chuẩn
 

package/docs/runtime-policy-design.md

@@ -73,7 +73,7 @@ The runtime separates the active autonomy profile from the project profile:
 | `workspace-write` | Default governed implementation mode. Existing protected-path, shell, capability, context, verify, and final gates remain active. |
 | `trusted-full-access` | Trusted automation mode for known repos. It can relax tool-registry blocks and capability filesystem scopes inside the guard, but protected paths, secret redaction, capability-lock integrity, and destructive/external confirmation still apply. |
 
-`PIAGENT_PERMISSION_PROFILE` can override the profile for a single run. Invalid values fail closed to `read-only`. Inside Pi, `/read-only`, `/workspace-write`, and `/full-access` set a session-local override without writing the project profile. Precedence is launch env, then session command, then project profile, then policy default. `permissionProfiles.allowedModes` in base policy acts like a managed allowlist; removing `trusted-full-access` from that list disables it for the installation.
+`PIAGENT_PERMISSION_PROFILE` can override the profile for a single run. Invalid values fail closed to `read-only`. Inside Pi, `/permission read-only`, `/permission workspace-write`, and `/permission full-access` set a session-local override without writing the project profile. Legacy aliases `/read-only`, `/workspace-write`, and `/full-access` still work. Precedence is launch env, then session command, then project profile, then policy default. `permissionProfiles.allowedModes` in base policy acts like a managed allowlist; removing `trusted-full-access` from that list disables it for the installation.
 
 ## Task lifecycle
 

package/docs/runtime-quality-baseline.md

@@ -29,7 +29,7 @@ Runtime behavior:
 - `read-only` chặn shell, write/edit, và unknown non-piagent tools;
 - `workspace-write` là default cho implementation có guard;
 - `trusted-full-access` nới tool/scope autonomy trong môi trường trusted nhưng không tắt protected paths, redaction, capability lock, hoặc human gate cho destructive/external action.
-- `/full-access <task>` bật `trusted-full-access` cho session hiện tại rồi gửi phần task còn lại cho agent; `/permission-status` hiển thị mode và boundary đang active.
+- `/permission full-access <task>` bật `trusted-full-access` cho session hiện tại rồi gửi phần task còn lại cho agent; `/permission status` hiển thị mode và boundary đang active. Alias `/full-access <task>` và `/permission-status` vẫn chạy.
 
 ## 1. Exec policy
 

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.2, 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/subagent-orchestration-capabilities.md

@@ -9,7 +9,7 @@ Package used:
 
 ## Kết luận
 
-Pi Agent Platform uses `pi-subagents` for child sessions, parallel read-only work, review loops, and structured handoffs. The platform keeps a safe default configuration and documents advanced commands separately so daily users can still start with `/task`.
+Pi Agent Platform uses `pi-subagents` for child sessions, parallel read-only work, review loops, and structured handoffs. The platform keeps a safe default configuration and documents advanced commands separately so daily users can still start with `/workflow task`.
 
 Core decisions:
 
@@ -44,7 +44,7 @@ Core decisions:
 - `scripts/setup.sh` / `scripts/install-global.sh`
   - optional `--with-web-access` installs `npm:pi-web-access@0.13.0` for web/docs research
 - Workflow prompts
-  - `/task`, `/plan`, `/review`, `/be-to-fe`, `/platform-improve` instruct the parent to auto-delegate when work is independent and bounded
+  - `/workflow task`, `/workflow plan`, `/workflow review`, `/workflow be-to-fe`, `/workflow platform-improve` instruct the parent to auto-delegate when work is independent and bounded
 - Docs
   - command reference lists prompt shortcuts, watchdog/profile commands, supervisor control, output/fork/worktree options
 
@@ -63,7 +63,7 @@ Core decisions:
 Daily implementation:
 
 ```text
-/task Implement <task>.
+/workflow task Implement <task>.
 ```
 
 Review until clean:

package/docs/subagents-and-multiagent.md

@@ -18,7 +18,7 @@ Pi core không có subagents built-in. Theo design của Pi, subagents là exten
 
 Từ `v0.3.7`, `scripts/setup.sh` mặc định cài `pi-subagents` và chạy config preset `safe`.
 
-Workflow prompts của platform dùng **solo-first orchestration policy**: khi anh chạy `/task`, `/be-to-fe`, `/platform-improve`, `/plan`, hoặc `/review`, parent agent đọc `piagent_orchestration_policy`, lập task tree/review lenses, rồi mới cân nhắc subagent cho phần việc độc lập. Anh không bắt buộc phải gọi `/run` nếu chỉ muốn task hoàn chỉnh, và platform cũng không spawn swarm khi task nhỏ.
+Workflow prompts của platform dùng **solo-first orchestration policy**: khi anh chạy `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, lập task tree/review lenses, rồi mới cân nhắc subagent cho phần việc độc lập. Anh không bắt buộc phải gọi `/run` nếu chỉ muốn task hoàn chỉnh, và platform cũng không spawn swarm khi task nhỏ. Alias cũ như `/task` vẫn giữ cùng policy.
 
 Kiểm tra nhanh policy trong Pi:
 
@@ -129,7 +129,7 @@ Giải nghĩa nhanh:
 Nếu cần bản tổng hợp cho team mới:
 
 ```text
-/piagent-commands subagents
+/commands subagents
 ```
 
 ## Gọi subagent tự nhiên
@@ -149,7 +149,7 @@ Run parallel research: external docs, local code context, and practical tradeoff
 Với workflow platform, còn có thể chỉ gọi:
 
 ```text
-/task Implement <task lớn>.
+/workflow task Implement <task lớn>.
 ```
 
 Parent agent sẽ tự quyết định:
@@ -324,7 +324,7 @@ Use:
 
 ```text
 /subagent-cost
-/piagent-usage
+/usage
 /session
 ```
 

package/docs/task-implementation-contract.md

@@ -131,7 +131,7 @@ Use piagent_context first.
 Use piagent_orchestration_policy; default to solo-first, create a compact task tree, and choose review lenses before spawning subagents.
 Use piagent_context_index_status/search as advisory navigation when available; verify cited files before editing.
 Use piagent_memory_status and search memory when relevant; memory is advisory only.
-Read .pi/project-context.md; if it is pending, stop and request /onboard-project.
+Read .pi/project-context.md; if it is pending, stop and request /onboard run.
 Create a Task Implementation Contract with piagent_task_start.
 Check large context with piagent_context_budget.
 Check complex/high-impact shell with piagent_exec_policy_check.
@@ -193,8 +193,8 @@ Exact command identity matters. If the task profile says `npm test`, record `npm
 
 ## Named implementation recipes
 
-- `/platform-improve`: dùng cho task cải tiến setup, docs, prompt, MCP, model, memory, runtime policy, hoặc subagent workflow của platform.
-- `/be-to-fe`: dùng cho task scout BE contract read-only rồi implement FE.
-- `/memory-policy`: dùng cho task kiểm tra/ghi nhớ explicit project memory.
+- `/workflow platform-improve`: dùng cho task cải tiến setup, docs, prompt, MCP, model, memory, runtime policy, hoặc subagent workflow của platform.
+- `/workflow be-to-fe`: dùng cho task scout BE contract read-only rồi implement FE.
+- `/memory`: dùng cho task kiểm tra/ghi nhớ explicit project memory.
 
 Hai recipe này vẫn phải tạo/giữ Task Implementation Contract khi có source writes.

package/docs/task-lifecycle-vietnamese.md

@@ -14,7 +14,7 @@ Contract fields và enforcement level nằm ở [task-implementation-contract.md
 
 Harness cung cấp:
 
-- `/scout` — pha read-only, không được sửa source. Dùng để map payment/auth/BE contract trước khi quyết có làm hay không.
+- `/workflow scout` — pha read-only, không được sửa source. Dùng để map payment/auth/BE contract trước khi quyết có làm hay không. Alias `/scout` vẫn chạy.
 - `piagent_context_index_search` — bản đồ node/edge/citation compact để tìm điểm vào repo. Kết quả là **advisory**: phải mở file thật và verify trước khi sửa.
 - `piagent_memory_search` + `piagent_memory_citation_record` — Field Guide và memory của project, cũng advisory, cũng phải verify lại.
 - `piagent_source_checkout` — cache repo ngoài để đọc có mục tiêu.
@@ -82,7 +82,7 @@ Nghĩa là `true`, `echo ok`, `npm test || true` không mua được chữ "done
 
 | Pha | Trạng thái | Căn cứ |
 |---|---|---|
-| Research | **Đủ** | `/scout`, context index, memory, Context7, source checkout |
+| Research | **Đủ** | `/workflow scout`, context index, memory, Context7, source checkout |
 | Plan | **Đủ** | `piagent_task_start` + 19 field contract + `workPlan` |
 | Execute | **Đủ** | Chặn trước thực thi ở mọi đường: tool, MCP, shell |
 | Verify | **Mạnh** | Bằng chứng phải quan sát được và khớp lệnh, không tự khai được |

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.2
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable
 cd /path/to/project
 pi
@@ -17,8 +17,9 @@ pi
 <select provider/model>
 /mcp
 /subagents-doctor
-/onboard-project
-/memory-policy
+/onboard
+/onboard run
+/memory
 ```
 
 ## Prerequisites
@@ -42,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.2
+npm install -g --ignore-scripts @piagent/platform@1.2.4
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -67,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.2`.
+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.
 
@@ -148,7 +165,8 @@ Rồi chạy:
 ```text
 /mcp
 /subagents-doctor
-/onboard-project
+/onboard
+/onboard run
 ```
 
 Output chính:
@@ -177,9 +195,9 @@ Nếu project chưa có profile/tech stack, dùng select-style flow để tránh
 
 `fullstack` bắt chọn frontend, backend và database. Nếu native select chưa có trong Pi host, command trả card compact kèm lệnh deterministic `/profile tech apply ...`.
 
-Nếu `.pi/project-context.md` còn `Generated: not yet`, không nên chạy `/task` implementation.
+Nếu `.pi/project-context.md` còn `Generated: not yet`, không nên chạy `/workflow task` implementation.
 
-Memory mặc định là project-scoped và explicit-only. Chạy `/memory-policy` để xem files/rules. Agent chỉ ghi durable memory khi user yêu cầu rõ ràng.
+Memory mặc định là project-scoped và explicit-only. Chạy `/memory` để xem files/rules. `/memory-policy` vẫn là alias. Agent chỉ ghi durable memory khi user yêu cầu rõ ràng.
 
 Đổi profile sau này:
 
@@ -268,31 +286,33 @@ Lệnh này wrap `pi --approve`; nó không bypass piagent guard.
 Requirement chưa rõ:
 
 ```text
-/discuss Tạo plan cho feature X. Chưa implement.
+/workflow discuss Tạo plan cho feature X. Chưa implement.
 ```
 
 Task rõ:
 
 ```text
-/task Implement feature X. Follow project profile, protected paths, required context, exec policy, context budget, tool policy, verify, trace, and task gate.
+/workflow task Implement feature X. Follow project profile, protected paths, required context, exec policy, context budget, tool policy, verify, trace, and task gate.
 ```
 
 Scout/audit read-only:
 
 ```text
-/scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
+/workflow scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
 ```
 
 Session nặng hoặc context overflow:
 
 ```text
-/fresh-scout <read-only scout>
-/fresh-task <bounded task>
-/fresh-be-to-fe <BE-readonly/FE request>
+/fresh scout <read-only scout>
+/fresh task <bounded task>
+/fresh be-to-fe <BE-readonly/FE request>
 ```
 
 Không paste full mandatory flow hằng ngày. Platform prompts/tools đã chứa checklist; input guard sẽ tự collapse boilerplate nếu paste nhầm.
 
+Alias cũ `/discuss`, `/task`, `/scout`, `/fresh-*` vẫn chạy cho power user, nhưng tài liệu onboard team dùng `/workflow`, `/name`, `/fresh`, và `/usage` để dễ nhớ hơn.
+
 Runtime gate tools:
 
 ```text
@@ -305,19 +325,19 @@ piagent_task_gate_check
 Task cải tiến platform:
 
 ```text
-/platform-improve Improve onboarding, model scope, MCP setup, and verification docs for team usage.
+/workflow platform-improve Improve onboarding, model scope, MCP setup, and verification docs for team usage.
 ```
 
 Task BE spec lên FE:
 
 ```text
-/be-to-fe Implement FE from BE contract <endpoint/spec>. Backend is read-only.
+/workflow be-to-fe Implement FE from BE contract <endpoint/spec>. Backend is read-only.
 ```
 
 Project memory:
 
 ```text
-/memory-policy
+/memory
 Remember: this repo uses pnpm, never npm.
 ```
 
@@ -343,7 +363,7 @@ bash /path/to/piagent/scripts/team-doctor.sh /path/to/project --strict-share
 bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --init
 ```
 
-Nếu doctor cảnh báo `project onboarding snapshot is still pending`, mở Pi trong project và chạy `/onboard-project`.
+Nếu doctor cảnh báo `project onboarding snapshot is still pending`, mở Pi trong project và chạy `/onboard run`.
 
 ## Không commit