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

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.0.1` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.0` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.0.1` |
+| 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.1` | 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.1
+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.1
+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.1` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.0.1`.
+`pi install git:github.com/Vt-mmm/piagent@v1.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.1 \
+  --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.1
+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.1`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.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.1
+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.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,11 +842,15 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.0.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.1` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.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.1 yêu cầu Pi `0.81.1`. |
+| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. 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. |
+| `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm add-on đã pin và Pi host. |
+| `piagent-uninstall --apply --project <path>` | Gỡ thêm profile, lock và `piagent-state/` của project. Không đụng credential, trust, session, todo, `.pi/memory/`. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
 | `piagent-install --stable` | Apply Pi package matching với helper hiện tại bằng resolved commit SHA. |
 | `piagent-install --version vX.Y.Z --resolve-tag` | Chỉ đổi Pi package; terminal helper giữ nguyên version. |
@@ -936,7 +940,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.0.1
+npm install -g --ignore-scripts @piagent/platform@1.1.0
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -42,7 +42,8 @@ pi install /path/to/piagent
 
 - `0.1.x`: local/internal pilot.
 - `0.2.x`: có guard ổn định và docs team.
-- `1.0.1`: đủ security review, MCP registry, adapter schema versioned.
+- `1.0.2`: đủ security review, MCP registry, adapter schema versioned.
+- `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