@piagent/platform 1.0.1 → 1.1.0

package/docs/quickstart-vietnamese.md

@@ -26,101 +26,29 @@ Support matrix của release hiện tại:
 | Native Windows | Chưa phải target rollout team; helper/shell policy cần Bash/POSIX semantics. |
 | WSL2 | Experimental, chưa release-gate. |
 
-Node.js phải từ `22.19.0` trở lên và Pi Coding Agent phải là `0.81.1`.
+Node.js phải từ `22.19.0` trở lên. Hai lệnh:
 
 ```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
-piagent-install --stable --dry-run
-piagent-install --stable
+npm install -g @piagent/platform
+piagent-setup
 ```
 
-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.1` là release hiện tại của docs này.
+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.
 
-Nếu chỉ cần cài package vào Pi và không cần terminal command helper:
+Nếu dùng [Herdr](https://herdr.dev/docs/install/) thì cài Herdr **trước** `piagent-setup`:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.1
+brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS hoặc Linux
 ```
 
-Nếu đang ở source checkout của platform, có thể preview và áp stable bằng helper:
+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.
 
-```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:
-
-```bash
-piagent-install --version vX.Y.Z --resolve-tag --dry-run
-piagent-install --version vX.Y.Z --resolve-tag
-```
-
-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:
+Vì chạy từ package đã cài, source ghi vào `.pi/settings.json` là `npm:@piagent/platform@<version>` — portable, commit được.
 
-```bash
-cd /path/to/project
-pi
-```
+Xong. Từ đây project nào cũng chỉ cần `cd` vào rồi gõ `pi`.
 
-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.
-```
-
-`/full-access <task>` chỉ bật full-access cho session hiện tại, không tự ghi `.pi/piagent-profile.json`.
-
-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
 
@@ -146,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
@@ -214,131 +104,74 @@ 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.1 \
-  --mcp-preset core \
-  --subagents-preset safe
-```
+Global đã cài rồi nên project sau chỉ cần init:
 
-Đổi profile sau này trong Pi:
-
-```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`.
-
-## Bước 5 — setup split/preseed nếu cần
+Nó ghi `npm:@piagent/platform@<version>` vào `.pi/settings.json` — portable, commit được cho cả team.
 
-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.1 \
-  --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.
-```
-
-Prompt mẫu khi chỉ cần scout/read-only:
-
-```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.
+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.
 
-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.
+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).
 
-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>
-```
+| 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).
 
-Prompt mẫu cho 2 recipe hay gặp:
+## Việc user vẫn phải làm thủ công
 
-```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."
-```
+- 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.
+- 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.
 
-Cache external source repo để đọc targeted trong Pi:
+Các việc này là credential/trust boundary, không nên automation mù.
 
-```text
-Use piagent_source_checkout for github.com/org/repo, inspect only relevant files, then summarize applicable patterns.
-```
+## Gỡ cài đặt
 
-Runtime gate tools có sẵn:
+`piagent-uninstall` mặc định là dry run: nó in ra sẽ gỡ những gì rồi thoát, không đụng vào đâu cả. Thêm `--apply` mới thực hiệ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
+```bash
+piagent-uninstall
+piagent-uninstall --apply
 ```
 
-Fallback bằng shell nếu cần:
+Mặc định chỉ gỡ Pi package của platform khỏi Pi settings global. Muốn gỡ rộng hơ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
+piagent-uninstall --apply --with-addons                    # + pi-mcp-adapter, pi-subagents, pi-web-access
+piagent-uninstall --apply --with-host                      # + Pi Coding Agent host
+piagent-uninstall --apply --project /path/to/project       # + profile, lock, piagent-state/ của project
+npm uninstall -g @piagent/platform                         # helper npm-global, gỡ riêng
 ```
 
-## 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.
-- 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.
+Có những thứ nó **không bao giờ** xoá, kể cả khi bật hết cờ: `auth.json`, `trust.json`, `sessions/`, `todos/`, và `.pi/memory/`. Đó là dữ liệu của anh chứ không phải state của platform. `AGENTS.md`, `.pi/settings.json`, `project-context.md` cũng được giữ vì sinh ra từ template rồi anh sửa tiếp — script liệt kê chúng ra để anh tự quyết.
 
-Các việc này là credential/trust boundary, không nên automation mù.
+Với `.pi/settings.json` nó chỉ bỏ đúng entry trỏ tới platform trong `packages`, phần còn lại giữ nguyên.
 
 ## Tài liệu chính
 

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.1 | Rollout guidance |
+| Surface | Status for v1.1.0 | 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.1` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.0` | 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.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
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.0.1 (helper package version)
-tag: v1.0.1
+currentRelease: v1.1.0 (helper package version)
+tag: v1.1.0
 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.1
+pi install git:github.com/Vt-mmm/piagent@v1.1.0
 ```
 
 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
@@ -141,6 +141,44 @@ piagent-install --version vPREVIOUS --resolve-tag
 piagent-doctor /path/to/project --strict-share
 ```
 
+## Uninstall
+
+Rollback moves between releases. Uninstall leaves entirely, and it is the flow a team member or an external user reaches for when this platform is no longer wanted on their machine.
+
+`piagent-uninstall` reports and exits; `--apply` performs the removal. The default is a report because the command edits Pi's global settings, which other tools also write to.
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+```
+
+Each additional layer is opt-in, so leaving the platform never takes the Pi host or a project's history with it by surprise:
+
+```bash
+piagent-uninstall --apply --with-addons               # pi-mcp-adapter, pi-subagents, pi-web-access
+piagent-uninstall --apply --with-host                 # the exact Pi Coding Agent host
+piagent-uninstall --apply --project /path/to/project  # a project's profile, lock, and runtime state
+npm uninstall -g @piagent/platform                    # the npm-global helper, removed separately
+```
+
+Removal reads the package entries registered in Pi's settings rather than assuming what the running version installs. A machine that first installed the platform before the namespace rename still has that older entry removed.
+
+### What uninstall will not remove
+
+These are operator data, not platform state, and no flag combination deletes them:
+
+| Kept | Why |
+|---|---|
+| `.pi/auth.json`, `.pi/trust.json` | Credentials and trust decisions. Re-earning them is not a cleanup step. |
+| `.pi/sessions/`, `.pi/todos/` | Work history that predates and outlives the platform. |
+| `.pi/memory/` | Accumulated project memory. Deleting it destroys work the platform only stored. |
+
+Files written from a template and then edited in place — `AGENTS.md`, `REVIEW_GUIDELINES.md`, `.mcp.json`, `.pi/settings.json`, `.pi/mcp.json`, `.pi/project-context.md`, `.pi/context-index.json`, `.pi/tech-stack.json` — are listed rather than deleted, because by the time uninstall runs they hold project content rather than template content.
+
+`.pi/settings.json` is Pi's file, not this platform's. Uninstall drops only the `packages` entry pointing here and leaves every other setting untouched.
+
+The global MCP baseline at `$PI_CODING_AGENT_DIR/mcp.json` and the subagent config beside it are shared files that may have been edited after install. `--with-addons` reports their paths instead of resetting them.
+
 ## Canonical release checklist
 
 Production docs must never advertise a tag that cannot yet be installed.
@@ -226,7 +264,13 @@ 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 is reported as unverified, not as a pass.
 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.1, 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.0, 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/task-lifecycle-vietnamese.md

@@ -0,0 +1,139 @@
+# Vòng đời một task: research → plan → execute → verify → loop
+
+## Mục tiêu
+
+Tài liệu này mô tả một task chạy qua platform từ đầu tới cuối, và nói thẳng harness hiện tại đỡ được khâu nào, chưa đỡ được khâu nào. Mọi nhận định đều dẫn tới dòng code cụ thể, để khi code đổi thì tài liệu này sai một cách kiểm tra được chứ không sai âm thầm.
+
+Contract fields và enforcement level nằm ở [task-implementation-contract.md](task-implementation-contract.md). Tài liệu này nói về *luồng*, không lặp lại field.
+
+## Năm pha
+
+### 1. Research — hiểu trước khi hứa
+
+Đầu vào: yêu cầu của người dùng, tài liệu spec, code sẵn có.
+
+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.
+- `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.
+- `piagent_document_read` — đọc spec `.md`/`.pdf`/`.docx` từ project hoặc folder đã cấp trong `additionalReadRoots` (ví dụ `~/Downloads`). Nội dung trả về là **dữ liệu**, không phải chỉ thị.
+- Context7 qua MCP cho tài liệu vendor. Ghi snapshot ngắn bằng `piagent_profile_tech_context_record`, không paste nguyên khối doc vào file project.
+
+Ràng buộc: `piagent_context_preflight` chạy **trước** (`task.md` bước 0). Nếu nó trả `fresh-session` thì dừng nạp context ở session này.
+
+### 2. Plan — biến hiểu biết thành cam kết kiểm được
+
+`piagent_task_start` dựng Task Implementation Contract. Đây là chỗ task trở thành thứ có thể chấm điểm:
+
+| Field | Nó ràng buộc điều gì |
+|---|---|
+| `riskLane` | `tiny` \| `normal` \| `high-risk` — quyết định mức gate |
+| `acceptanceCriteria` | Định nghĩa "xong", viết trước khi làm |
+| `scope` / `outOfScope` | Ranh giới, để review biết cái gì là lạc đề |
+| `protectedPaths` | Đường không được đụng |
+| `verifyCommands` | **Lệnh chính xác** sẽ dùng làm bằng chứng |
+| `reviewLenses` | `correctness` \| `tests` \| `scope` \| `security` \| `docs` \| `release` \| `package` |
+| `workPlan` | Cây task tối đa 12 node, mỗi node có `role` và `mode` |
+
+`workPlan[].mode` là `read-only` \| `single-writer` \| `review`. Mặc định là single-writer: chỉ một tác nhân được ghi, trừ khi người dùng yêu cầu rõ parallel writers.
+
+`piagent_orchestration_policy` quyết định có gọi subagent không. Chính sách là solo-first — subagent chỉ dùng khi việc đó độc lập và nặng phần đọc.
+
+### 3. Execute — làm trong hàng rào
+
+Trong lúc làm, guard chặn trước khi thực thi, không phải sau:
+
+- Protected path: chặn ở `read`, `write`, `edit`, `grep`, `find`, `ls`, tool MCP, và cả đường vòng qua shell.
+- `piagent_exec_policy_check` — bắt buộc trước lệnh shell vượt quá read/list/test.
+- `piagent_tool_policy_check` — bắt buộc trước tool MCP/app ngoài piagent.
+- `piagent_context_budget` — kiểm trước khi nạp file lớn hoặc lạ.
+- `piagent_context_record` — ghi lại đọc file nào, vì lý do gì.
+
+### 4. Verify — chỗ mạnh nhất của harness
+
+Đây là phần được thiết kế kỹ nhất, và đáng để hiểu chính xác.
+
+Bằng chứng verify **không phải** thứ agent tự khai. Guard nghe `tool_result` của Pi và ghi vào sổ `.pi/piagent-state/observed-bash.jsonl` ([`piagent-guard.ts:1378`](../packages/piagent-core/extensions/piagent-guard.ts)). `piagent_verify_record` chỉ nhận bằng chứng khớp được với một quan sát thật, sau thời điểm task bắt đầu.
+
+`evaluateTaskGate` ([`piagent-guard.ts:3125`](../packages/piagent-core/extensions/piagent-guard.ts)) đòi ba điều kiện cộng dồn để một bằng chứng được tính là **pass**:
+
+```
+evidence.exitCode === 0
+&& evidence.observed === true            // đã quan sát được, không phải khai báo
+&& evidence.matchedProfileCommand === true  // khớp đúng verifyCommands của task
+```
+
+Thiếu bất kỳ điều nào thì bằng chứng vẫn được ghi, nhưng chỉ ở mức advisory và gate không tính. Cụ thể:
+
+- `observed !== true` → cảnh báo "Unobserved verify evidence is ignored by the passing verify gate."
+- `observed === true` nhưng lệnh không khớp `verifyCommands` → "advisory only".
+
+Nghĩa là `true`, `echo ok`, `npm test || true` không mua được chữ "done". Đó là chủ ý: một cổng có thể lách được thì tệ hơn không có cổng, vì nó vẫn hiện màu xanh.
+
+`piagent_task_gate_check` trả `pass` hoặc `fail` kèm danh sách `missing`. `task.md` bước 16: gate fail thì outcome là `blocked`/`partial`, **không phải** `done`.
+
+### 5. Fail → loop lại
+
+Đây là chỗ đứt. Xem mục [Chỗ đứt, nói chính xác](#chỗ-đứt-nói-chính-xác).
+
+## Pi hiện tại xử lý tới đâu
+
+| Pha | Trạng thái | Căn cứ |
+|---|---|---|
+| Research | **Đủ** | `/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 |
+| Fail → loop | **Nửa vời** | Phát hiện được, từ chối nhận done được, nhưng không mang được state qua lần sau |
+
+### Chỗ đứt, nói chính xác
+
+Harness **phát hiện** thất bại tốt:
+
+- `trace.outcome` có `failed`, `blocked`, `partial` bên cạnh `completed`.
+- `task.md` bước 18: verify không chạy được thì dừng và báo blocker chính xác, không được gọi là done.
+- Gate trả `missing` liệt kê đúng thứ còn thiếu.
+
+Nhưng nó **không mang được gì sang lần thử sau**:
+
+1. **Contract không có bộ đếm lần thử.** Không có `attempt`, không có `previousAttempts`. Lần thử thứ hai bắt đầu như thể chưa từng có lần một.
+2. **`workPlan[].status` không có giá trị `failed`.** Enum chỉ là `pending` \| `in-progress` \| `done` \| `skipped` ([`schemas/task-contract.schema.json`](../schemas/task-contract.schema.json)). Một node đã thử và hỏng chỉ có thể ghi là `skipped` — mất nghĩa.
+3. **Không có chỗ ghi giả thuyết đã loại.** Verify fail vì lý do gì, đã thử cách nào, tại sao không được — không field nào giữ. Lần sau agent rất dễ thử lại đúng cách đã hỏng.
+4. **Không có trần số vòng.** Không có gì chặn loop vô hạn ngoài sự kiên nhẫn của người dùng.
+
+`/review-loop` có tồn tại và đúng là loop, nhưng nó đến từ add-on `pi-subagents` chứ không phải platform này, và nó lặp vòng review→fix, không phải vòng research→plan→execute→verify.
+
+### Đề xuất để khép vòng
+
+Thêm vào contract, không đổi thứ đang có:
+
+```jsonc
+{
+  "attempt": 2,                    // lần thử hiện tại
+  "maxAttempts": 3,                // trần, gate fail cứng khi vượt
+  "previousAttempts": [
+    {
+      "attempt": 1,
+      "failedAt": "verify",        // research | plan | execute | verify
+      "reason": "npm test — 3 test đỏ ở auth/session",
+      "ruledOut": "Không phải do token expiry; đã kiểm bằng fixture cố định giờ."
+    }
+  ]
+}
+```
+
+Và mở `workPlan[].status` thêm giá trị `failed`.
+
+Chi phí: một field mảng trong schema, một nhánh trong `evaluateTaskGate`, một bước trong `task.md`. Đổi lại, lần thử thứ hai đọc được lần thứ nhất đã loại trừ gì — đó là toàn bộ giá trị của việc loop thay vì làm lại.
+
+Đây là đề xuất, chưa implement. Cần chốt trước khi làm.
+
+## Liên quan
+
+- [task-implementation-contract.md](task-implementation-contract.md) — field và enforcement level
+- [workflow-recipes.md](workflow-recipes.md) — công thức cho từng loại việc
+- [runtime-policy-design.md](runtime-policy-design.md) — thiết kế lớp policy
+- [security-threat-model.md](security-threat-model.md) — giả định, vector, và rủi ro còn lại
+- [command-reference-vietnamese.md](command-reference-vietnamese.md) — giải thích từng lệnh