@piagent/platform 1.0.2 → 1.1.1

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.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.0.2` |
+| Registry distribution | `npm:@piagent/platform@1.1.1` |
 | 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.1` | 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.1
 ```
 
 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.1
 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.1` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.1.1`.
 
 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.1 \
   --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.1
 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.1`. 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.1
 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.1 \
   --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.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.1` | 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.1
 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
 

package/docs/release-install-policy.md

@@ -8,9 +8,9 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 ## Supported runtime matrix
 
-All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.81.1`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
+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.0.2 | Rollout guidance |
+| Surface | Status for v1.1.1 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.0.2` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.1` | 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. |
@@ -52,8 +52,8 @@ Use this flow when the team needs both terminal commands and the Pi package:
 
 ```bash
 node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.2
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
+npm install -g --ignore-scripts @piagent/platform@1.1.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.0.2 (helper package version)
-tag: v1.0.2
+currentRelease: v1.1.1 (helper package version)
+tag: v1.1.1
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.2
+pi install git:github.com/Vt-mmm/piagent@v1.1.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -89,7 +89,7 @@ Direct `pi install` does not create `piagent-*` commands on `PATH`.
 Update the exact supported Pi host first, then the npm-global helper, then let that target helper resolve and install its matching stable 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
@@ -192,9 +192,12 @@ Before broad team access, a repository administrator must enable these external
 3. Enable Dependency graph, Dependabot alerts, and Dependabot security updates. Keep `.github/dependabot.yml` enabled for scheduled npm and GitHub Actions update pull requests.
 4. Enable GitHub private vulnerability reporting so the form linked by `SECURITY.md` works before public rollout.
 5. Keep secret scanning and push protection enabled. Review CodeQL results after the workflow's first successful run.
+6. Add the **Code scanning results** check to the `main` branch ruleset and set its alert threshold so that a new high-severity CodeQL alert blocks the merge. The `analyze (...)` jobs required above only prove the analysis ran and uploaded its SARIF; they succeed just as well when the analysis found new high-severity alerts. Without this separate check, a pull request merges green with open high alerts, which is what happened on `v1.1.1`. Requiring the `analyze` jobs is still necessary — it catches an analysis that failed to run — but it is not the results gate and must not be mistaken for one.
 
 Verify these settings in GitHub **Settings → Rules** and **Settings → Code security and analysis**. Treat any missing control as an explicit rollout blocker, not as a passing source-code gate. Repository rules also close the remaining mutability risk of bootstrap-by-tag; tag-to-SHA resolution inside `piagent-install` alone cannot protect the helper package before it starts.
 
+Alerts dismissed as false positives carry their reason in the dismissal comment, and the reason belongs in the source as well when the flagged shape is deliberate. An alert dismissed without a written reason is indistinguishable from an alert nobody read.
+
 ### Required npm publishing controls
 
 The publish workflow authenticates with the `NPM_TOKEN` repository secret. That token needs three things, and read-and-write access alone is not enough:
@@ -264,7 +267,15 @@ Re-running the workflow from a branch instead skips publishing, because the publ
    ```
 
    The open release pull request should then resolve against the same commit history. This bypass exists only to reconcile reviewed PR checks with tag-first Vercel promotion; it must never be used for an unreviewed commit or a force-push. If Vercel auto-deploys `main`, this exact fast-forward is the production promotion. For an explicit CLI deploy instead, check out the exact tag, run `vercel link --cwd docs-site --project pi-agent`, require `npm run vercel:preflight` to pass, then deploy with `vercel --cwd docs-site --prod`.
-8. Verify the live docs version, links, canonical domain, and install commands.
+8. Verify the live docs site at every address it resolves to, then read the page for links and install commands.
+
+   ```bash
+   npm run site:check
+   ```
+
+   Opening the site in a browser does not answer this. The domain has several address records, so one can be dead or looping while every manual look lands on a healthy one. This resolves both hosts, asks each address directly with the right `Host` header and SNI, and requires each to return the released version. A redirect from an address back to its own host is reported as a loop rather than followed.
+
+   An address the machine has no route to ends the run. It is reported separately from a site failure, because the machine is what is missing rather than the site, but it is not a pass either — the release gate must not report that it verified every address in a run where it verified fewer. Run the check from a machine with routes to every address family the domain publishes. `--allow-unverified` accepts the gap deliberately and names it in the summary; use it only when the missing route is understood and the remaining addresses were verified.
 9. Publish the already-reviewed draft only after production verification passes:
 
    ```bash

package/docs/security-threat-model.md

@@ -21,7 +21,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.0.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.1.1, 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