@piagent/platform 1.0.2 → 1.1.0

package/docs/command-reference-vietnamese.md

@@ -177,6 +177,45 @@ Tech stack option theo profile:
 
 Sau khi chọn tech, platform tạo `.pi/tech-stack.json` và các file `.pi/tech-context/<tech>.json`. `/onboard-project` sẽ đưa các pointer này vào `.pi/context-index.json`. File context chỉ nên chứa tóm tắt ngắn/citation từ Context7, không lưu nguyên văn docs dài, token, session, hoặc secret.
 
+## Đọc tài liệu ngoài project
+
+Tài liệu tải về `~/Downloads` rồi kéo vào CLI thường không đọc được, vì mặc định agent chỉ làm việc trong project. Tool `piagent_document_read` mở đúng một khe: đọc **tài liệu**, **chỉ đọc**, trong các folder đã cấp trước.
+
+| Thành phần | Giá trị |
+|---|---|
+| Tool | `piagent_document_read` |
+| Input | `path` — absolute, `~/...`, hoặc relative theo project |
+| Định dạng | `.md`, `.markdown`, `.txt`, `.text`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`, `.pdf`, `.docx` |
+| Giới hạn | 12 MB/file; 400.000 ký tự sau khi trích, dài hơn thì cắt và báo `truncated` |
+| Cấp quyền | `additionalReadRoots` trong `.pi/piagent-profile.json`, hoặc biến môi trường `PIAGENT_ADDITIONAL_READ_ROOTS` |
+
+Cấp folder cố định trong profile:
+
+```json
+{
+  "additionalReadRoots": ["~/Downloads", "~/Documents/specs"]
+}
+```
+
+Cấp tạm cho một session, ngăn cách bằng `:` giống `PATH`:
+
+```bash
+PIAGENT_ADDITIONAL_READ_ROOTS="$HOME/Downloads:$HOME/Documents/specs" pi
+```
+
+Sau đó nói thẳng path là được: `Đọc ~/Downloads/spec-v2.docx rồi tóm tắt yêu cầu`.
+
+Bốn ràng buộc không đổi khi cấp thêm root:
+
+- **Chỉ đọc.** Root được cấp không mở quyền ghi, xoá, hay chạy lệnh trong đó.
+- **Chỉ tài liệu.** File nằm trong root được cấp nhưng sai đuôi — `.pem`, `.sh`, `.env` — vẫn bị từ chối.
+- **`protectedPaths` luôn thắng.** Root được cấp không mở được path mà project đang bảo vệ.
+- **Nội dung là dữ liệu, không phải lệnh.** Text trả về đã qua redaction và có header nói rõ đây là dữ liệu người dùng; câu lệnh viết trong tài liệu không được thi hành.
+
+Cả hai kiểm tra — nằm trong root và đúng đuôi — đều chạy trên path đã canonical hoá. Nên symlink trong root mà trỏ ra ngoài bị chặn, và symlink tên `notes.md` trỏ vào `id_rsa` cũng bị chặn.
+
+`.docx` đọc trực tiếp, không cần cài gì; text bị xoá bởi tracked change chưa accept sẽ không lẫn vào nội dung. `.pdf` cần `pdftotext` (macOS `brew install poppler`, Debian/Ubuntu `apt install poppler-utils`); thiếu binary thì tool báo thiếu chứ không trả tài liệu rỗng.
+
 ## Command native của Pi
 
 Các command này thuộc Pi core hoặc package Pi chính. Tên/availability có thể phụ thuộc version Pi.
@@ -379,11 +418,11 @@ 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.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. |
+| `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.1.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.0` | 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.2 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. 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á 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. |

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.2` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.0` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.0.2` |
+| Registry distribution | `npm:@piagent/platform@1.1.0` |
 | 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.2` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.0` | 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.2
+pi install git:github.com/Vt-mmm/piagent@v1.1.0
 ```
 
 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.
@@ -64,13 +64,13 @@ 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.2
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @piagent/platform@1.1.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`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`.
+`pi install git:github.com/Vt-mmm/piagent@v1.1.0` 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.1.0`.
 
 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.2 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -175,7 +175,7 @@ Files không commit:
 Full platform update phải đồng bộ Pi host, npm-global helper và Pi package:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+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

package/docs/herdr-workflow.md

@@ -4,11 +4,32 @@
 
 Herdr dùng để quản lý nhiều session/pane agent. Pi core không cần tự làm subagent ngay từ đầu.
 
+## Cài Herdr
+
+```bash
+brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS hoặc Linux
+```
+
+Bản `curl` là cách herdr.dev đặt làm mặc định, nhưng nó chạy script tải về ngay lúc cài. Muốn xem được thứ mình chạy thì dùng `brew`, hoặc tải binary từ [GitHub releases](https://github.com/ogulcancelik/herdr/releases) rồi `chmod +x` và đưa vào `PATH`.
+
+Stable chỉ hỗ trợ macOS và Linux. Windows mới có bản preview, và cũng nằm ngoài runtime matrix của platform này.
+
 ## Setup integration
 
+`piagent-setup` đã chạy `herdr integration install pi` giùm, với điều kiện `herdr` có sẵn trên `PATH` lúc đó. Không có thì nó bỏ qua kèm cảnh báo ra stderr — nên thứ tự đúng là cài Herdr trước, rồi mới `piagent-setup`.
+
+Cài Herdr sau khi đã setup thì chạy lại:
+
+```bash
+piagent-setup --global-only
+```
+
+Kiểm tra hoặc cài tay:
+
 ```bash
-herdr integration install pi
 herdr integration status
+herdr integration install pi
 ```
 
 Nếu dùng custom Pi agent dir:

package/docs/mcp-and-tools.md

@@ -2,7 +2,19 @@
 
 ## Kết luận hiện tại
 
-Pi core không hard-code MCP. Platform của mình cài `pi-mcp-adapter` để Pi dùng MCP theo kiểu token-efficient: một proxy tool `mcp(...)`, server lazy-connect, metadata cache, output guard. Project profile chỉ khai báo capability được phép; MCP config mới khai báo server thật.
+Pi core không hard-code MCP. Platform của mình cài `pi-mcp-adapter` để Pi dùng MCP theo kiểu token-efficient: một proxy tool tên `mcp`, server lazy-connect, metadata cache, output guard. Project profile chỉ khai báo capability được phép; MCP config mới khai báo server thật.
+
+**Ba thứ tên giống nhau nhưng không liên quan nhau** — chỗ này gây nhầm nhiều nhất:
+
+| Thứ | Ở đâu | Là gì |
+|---|---|---|
+| `mcpCapabilities: ["github", ...]` | `.pi/piagent-profile.json` | Nhãn capability dùng cho tool registry |
+| `toolCapabilities: { "github": ["github"] }` | `base-policy.json` | Map một tool **tên là `github`** sang capability |
+| server `github` | `~/.config/mcp/mcp.json` | Server MCP thật, chạy qua Docker |
+
+Không có dòng code nào map capability name sang MCP server id. Khai `"github"` trong `mcpCapabilities` **không** bật server MCP `github`, và ngược lại.
+
+`toolPrefix` trong MCP config (`"server" | "none" | "short"`) chỉ đặt tên cho **direct tools** khi bật `directTools: true`. Nó không đổi tên proxy tool — proxy luôn là `mcp`.
 
 Từ `v0.3.7`, repo có thêm:
 
@@ -13,7 +25,17 @@ Từ `v0.3.7`, repo có thêm:
 
 ## Cấu hình một lần cho máy cá nhân/team
 
-Global install mặc định sẽ cài adapter và seed preset `core` nếu dùng `scripts/setup.sh` hoặc `scripts/install-global.sh --with-mcp`:
+Cả `piagent-setup` và `piagent-install` đều cài adapter và seed preset `core` **mặc định**. Muốn bỏ qua thì thêm `--no-mcp`.
+
+Ghi config **không** bằng dùng được ngay. Server connect lazy, nên mỗi server còn cần thứ của nó trước lần gọi đầu:
+
+| Server (preset `core`) | Còn cần gì |
+|---|---|
+| `context7` | Không bắt buộc. `CONTEXT7_API_KEY` chỉ để tăng quota |
+| `chrome-devtools` | Chrome cài sẵn trên máy |
+| `github` | **Docker đang chạy** + `export GITHUB_PERSONAL_ACCESS_TOKEN` |
+
+`piagent-mcp --list` in ra yêu cầu của từng server; lệnh apply cũng in danh sách này ra stderr ngay sau khi ghi config.
 
 ```bash
 bash /path/to/piagent/scripts/setup.sh . \
@@ -237,7 +259,9 @@ Tool:
 piagent_tool_policy_check
 ```
 
-Default `toolRegistry=advisory`: agent nhận warning khi tool chưa map capability. Project ổn định có thể bật `toolRegistry=enforce` trong `.pi/piagent-profile.json`.
+Default `toolRegistry=advisory`: tool chưa map capability vẫn chạy, nhưng guard phát một notice mức `warning` — **một lần cho mỗi tool trong mỗi session**, không phải mỗi lần gọi.
+
+`toolRegistry=enforce` thì đổi notice đó thành block. Cân nhắc trước khi bật: proxy tool của MCP tên là `mcp`, không nằm trong `alwaysAllowedTools` cũng không có trong `toolCapabilities`, nên **enforce sẽ chặn toàn bộ MCP**. Khai thêm `mcpCapabilities` không gỡ được, vì không có mapping nào từ capability name sang MCP server. Ngoại lệ duy nhất là permission profile `trusted-full-access`.
 
 Protected-path gate độc lập với registry mode. Dù tool registry đang `advisory`, mọi raw tool call có path-like string trỏ vào protected path sẽ bị block trước khi tool chạy. Cơ chế này áp dụng cho Pi built-ins (`read`, `write`, `edit`, `grep`, `find`, `ls`) và custom/MCP tools nếu tool call đi qua Pi `tool_call` hook.
 

package/docs/operator-manual-vietnamese.md

@@ -13,17 +13,17 @@ Từ đó Pi có thể login provider, chọn model, onboard project, chạy tas
 
 Runtime team nên pin release tag hoặc commit đã review. Latest chỉ dùng cho máy cá nhân/sandbox khi chấp nhận cập nhật nhanh.
 
-Support matrix release 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 `piagent-doctor` + smoke test trước khi rollout rộng; native Windows chưa phải target rollout team; WSL2 experimental/chưa release-gate. Node.js tối thiểu là `22.19.0`, Pi Coding Agent là `0.81.1`.
+Support matrix release 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 `piagent-doctor` + smoke test trước khi rollout rộng; native Windows chưa phải target rollout team; WSL2 experimental/chưa release-gate. Node.js tối thiểu là `22.19.0`, Pi Coding Agent là `0.82.0`.
 
 ```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.2
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @piagent/platform@1.1.0
 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.2`. 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.1.0`. 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:
 
@@ -37,7 +37,7 @@ bash scripts/install-global.sh --stable
 Full update phải đồng bộ exact Pi host trước, rồi npm-global helper và Pi package matching:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+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
@@ -98,8 +98,8 @@ install package once
 ### Cài Pi và package platform
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.2
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @piagent/platform@1.1.0
 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.2 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,10 +842,10 @@ 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.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. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.0` | 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.2 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. 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. |
 | `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. |
@@ -940,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.2
+npm install -g --ignore-scripts @piagent/platform@1.1.0
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -43,6 +43,7 @@ pi install /path/to/piagent
 - `0.1.x`: local/internal pilot.
 - `0.2.x`: có guard ổn định và docs team.
 - `1.0.2`: đủ security review, MCP registry, adapter schema versioned.
+- `1.1.0`: đọc document ngoài project qua `additionalReadRoots`, MCP baseline bật mặc định ở cả hai lệnh install, pin Pi host `0.82.0`.
 
 ## Không publish
 

package/docs/quickstart-vietnamese.md

@@ -33,105 +33,22 @@ 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.
+Chạy `piagent-setup` ngay trong thư mục project. Nó tự cài đúng Pi Coding Agent `0.82.0` 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, subagents, và Herdr Pi integration nếu `herdr` đã có sẵn trên `PATH`; thêm `--no-mcp`, `--no-subagents`, `--no-herdr` 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.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.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.2
-```
-
-Nếu đang ở source checkout của platform, có thể preview và áp stable bằng helper:
-
-```bash
-bash scripts/install-global.sh --stable --dry-run
-bash scripts/install-global.sh --stable
-```
-
-Helper stable sẽ resolve tag release hiện tại thành commit SHA trước khi install, nên user vẫn dùng lệnh ngắn nhưng team nhận source bất biến hơn.
-
-Khi update toàn bộ platform, cập nhật exact Pi host trước rồi dùng helper target để cài Pi package tương ứng:
-
-```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@X.Y.Z
-piagent-install --stable --dry-run
-piagent-install --stable
-```
-
-Rollback toàn bộ dùng cùng flow với `vPREVIOUS`, nhưng phải lấy exact host version từ release policy của target và đánh giá lại dependency risk trước khi hạ host. Nếu chủ ý chỉ đổi Pi package và giữ host/helper hiện tại:
+Nếu dùng [Herdr](https://herdr.dev/docs/install/) thì cài Herdr **trước** `piagent-setup`:
 
 ```bash
-piagent-install --version vX.Y.Z --resolve-tag --dry-run
-piagent-install --version vX.Y.Z --resolve-tag
+brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS hoặc Linux
 ```
 
-Checklist release canonical nằm tại [release-install-policy.md](release-install-policy.md).
-
-Máy cá nhân hoặc sandbox có thể dùng latest nếu chấp nhận cập nhật nhanh:
-
-```bash
-bash scripts/install-global.sh --dev --dry-run
-bash scripts/install-global.sh --dev
-```
-
-Sau bước này, project mới không cần chạy bash init profile. Chỉ cần:
-
-```bash
-cd /path/to/project
-pi
-```
+Không có `herdr` trên `PATH` thì bước integration bị bỏ qua kèm cảnh báo, cài Herdr sau phải chạy lại `piagent-setup --global-only`. Bản `curl` chạy script tải về lúc cài; muốn kiểm tra được thì dùng `brew` hoặc tải từ [GitHub releases](https://github.com/ogulcancelik/herdr/releases). Herdr bản stable hỗ trợ macOS và Linux; Windows mới ở mức preview, mà cũng nằm ngoài runtime matrix của platform này.
 
-Với project đã tin cậy, có thể dùng wrapper để Pi tự approve project-local resources cho lần chạy đó:
-
-```bash
-piagent-auto
-```
-
-Read-only auto-run:
-
-```bash
-piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
-```
-
-Trusted full-access style run cho repo đã kiểm soát:
-
-```bash
-piagent-auto --full-access -p "Run the trusted local benchmark suite."
-```
-
-Wrapper này không bypass piagent guard; nó wrap `pi --approve` và set permission profile cho lần chạy. Dù dùng `--full-access`, protected paths, redaction, destructive shell checks, task gate, và verify evidence vẫn chạy.
-
-Nếu đã ở trong Pi session, dùng slash command cho nhanh:
-
-```text
-/permission-status
-/full-access Implement/refactor task trong repo trusted này.
-```
+Vì chạy từ package đã cài, source ghi vào `.pi/settings.json` là `npm:@piagent/platform@<version>` — portable, commit được.
 
-`/full-access <task>` chỉ bật full-access cho session hiện tại, không tự ghi `.pi/piagent-profile.json`.
+Xong. Từ đây project nào cũng chỉ cần `cd` vào rồi gõ `pi`.
 
-Nếu chat box/ảnh chụp trả về local path thay vì attachment ảnh, dán path đó trực tiếp vào prompt:
-
-```text
-/scout Check UI issue from screenshot /var/folders/.../screenshot.png
-```
-
-Platform sẽ tự attach ảnh và rewrite prompt thành `[image1]` trước khi model xử lý. Hỗ trợ `.png/.jpg/.jpeg/.gif/.webp/.bmp`, tối đa 4 ảnh, 8 MB mỗi ảnh.
+Rollout team pin từng bước, update, rollback, và channel `--dev` cho máy cá nhân: [release-install-policy.md](release-install-policy.md).
 
 ## Bước 2 — login OAuth OpenAI Codex/ChatGPT hoặc Claude/Anthropic
 
@@ -157,47 +74,9 @@ Sau khi login và chọn model intended cho project understanding:
 /memory-policy
 ```
 
-Global setup đã config sẵn `enabledModels` cho các provider model families. Anh đổi model bằng selector/hotkey:
-
-```text
-Ctrl+L       # model selector
-Ctrl+P       # đổi model trong scope
-Shift+Tab    # đổi thinking
-```
-
-Nếu muốn xem/re-apply model scope từ terminal: `piagent-models` và `piagent-model-scope --preset full`.
-
-Nếu muốn xem/re-apply MCP baseline từ terminal:
-
-```bash
-piagent-mcp --preset core --scope global --replace
-piagent-mcp --preset popular --scope global --replace
-piagent-mcp --list
-```
-
-Nếu clone repo GitHub và chưa link npm bin, dùng fallback:
-
-```bash
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
-```
-
-Nếu muốn xem/re-apply subagents baseline từ terminal:
-
-```bash
-piagent-subagents --preset safe
-# fallback:
-bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
-```
+`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).
 
-Nếu muốn dùng builtin `researcher` cho web/docs research trong Pi:
-
-```bash
-pi install npm:pi-web-access@0.13.0
-# hoặc setup từ đầu:
-bash /path/to/piagent/scripts/setup.sh . --with-web-access
-```
-
-Lệnh này yêu cầu model đọc qua project theo phạm vi có kiểm soát, rồi ghi:
+`/onboard-project` 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
@@ -225,120 +104,41 @@ Nếu chưa có profile/tech stack, dùng select-style flow để tránh agent t
 
 ## Bước 4 — init thêm project khác
 
-```bash
-bash /path/to/piagent/scripts/setup.sh /path/to/project \
-  --project-only \
-  --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.2 \
-  --mcp-preset core \
-  --subagents-preset safe
-```
-
-Đổi profile sau này trong Pi:
+Global đã cài rồi nên project sau chỉ cần init:
 
-```text
-/profile list
-/profile setup
-/profile tech setup
-/profile be-readonly-fe
+```bash
+cd /path/to/project
+piagent-setup --project-only
 ```
 
-Profile built-in: `generic`, `web-frontend`, `backend-api`, `be-readonly-fe`, `fullstack`, `node-typescript`, `python`, `data`, `devops`, `mobile`, `docs`.
+Nó ghi `npm:@piagent/platform@<version>` vào `.pi/settings.json` — portable, commit được cho cả team.
 
-## Bước 5 — setup split/preseed nếu cần
-
-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.2 \
-  --mcp-preset core \
-  --subagents-preset safe
-```
+Đổi profile sau này thì gõ `/profile setup` trong Pi. Profile built-in: `generic`, `web-frontend`, `backend-api`, `be-readonly-fe`, `fullstack`, `node-typescript`, `python`, `data`, `devops`, `mobile`, `docs`.
 
-## Bước 6 — chạy hằng ngày
+## Bước 5 — chạy hằng ngày
 
 ```bash
-herdr
 cd <project>
 pi
 ```
 
-Prompt mẫu khi requirement chưa rõ:
-
-```text
-/discuss Cải tiến workflow onboarding cho team mới. Chưa implement, chỉ hỏi lại phần còn thiếu và đề xuất plan.
-```
-
-Prompt mẫu khi đã rõ task:
-
-```text
-/task Implement this request. Use piagent_context, piagent_task_start, piagent_context_budget, piagent_exec_policy_check when shell is needed, piagent_verify_record, piagent_trace_record, and piagent_task_gate_check before done.
-```
+Rồi mô tả việc cần làm bằng tiếng Việt hoặc tiếng Anh. 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.
 
-Prompt mẫu khi chỉ cần scout/read-only:
+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).
 
-```text
-/scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
-```
-
-Nếu session đang nặng hoặc gặp context overflow:
-
-```text
-/fresh-scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
-/fresh-task Implement <bounded task>.
-/fresh-be-to-fe Implement FE support from <BE contract>. Backend read-only.
-```
-
-Không paste full mandatory flow hằng ngày. Từ `v0.3.21`, input guard tự collapse mandatory-flow boilerplate và fresh workflow tự mở session mới khi cần.
-
-Từ `v0.3.21`, `/task` có auto-delegation policy. Với task đủ lớn, parent agent phải tự cân nhắc dùng `piagent-scout`, `piagent-planner`, hoặc `piagent-reviewer`; anh không cần tự gọi `/run` nếu không muốn ép orchestration.
-
-Các workflow package đáng dùng khi muốn ép rõ shape:
-
-```text
-/parallel-review current diff
-/review-loop current diff max 3 rounds
-/parallel-research <question cần external evidence + local code context>
-/parallel-context-build <task lớn cần context handoff>
-```
-
-Prompt mẫu cho 2 recipe hay gặp:
-
-```text
-/piagent-commands subagents
-/platform-improve Improve model selection, MCP setup, and onboarding docs for a public team package.
-/be-to-fe Implement FE from BE spec <endpoint/spec>. Backend read-only.
-/context-index search auth
-/memory-policy Show project memory policy and safe remember workflow.
-/run piagent-scout "Map target area read-only before planning."
-/run piagent-reviewer "Review current diff before final handoff."
-```
-
-Cache external source repo để đọc targeted trong Pi:
-
-```text
-Use piagent_source_checkout for github.com/org/repo, inspect only relevant files, then summarize applicable patterns.
-```
-
-Runtime gate tools có sẵn:
-
-```text
-piagent_exec_policy_check      # check shell command
-piagent_context_budget         # check context size/hard cap
-piagent_tool_policy_check      # check tool capability
-piagent_task_gate_check        # check before final DONE
-```
-
-Fallback bằng shell nếu cần:
-
-```bash
-PIAGENT_PLATFORM_HOME=/path/to/piagent
-bash "$PIAGENT_PLATFORM_HOME/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh" \
-  github.com/org/repo \
-  --path-only
-```
+| 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. |
+| `/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).
 
 ## Việc user vẫn phải làm thủ công