@piagent/platform 1.0.2 → 1.1.0

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.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.2` | 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.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
 ```
@@ -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.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.2
+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
@@ -264,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.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.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

package/docs/team-onboarding.md

@@ -8,8 +8,8 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 
 ```bash
 node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.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
 cd /path/to/project
 pi
@@ -24,13 +24,14 @@ pi
 ## Prerequisites
 
 - Node.js >=22.19.0.
-- Pi Coding Agent `0.81.1`.
+- Pi Coding Agent `0.82.0`.
 - Runtime rollout:
   - verified: macOS Apple Silicon + Bash, Linux x64 + Bash;
   - supported target cần smoke trước khi rollout rộng: macOS Intel + Bash, Linux ARM64 + Bash;
   - chưa dùng làm target rollout team: native Windows; WSL2 chỉ experimental.
 - `pi` có trên `PATH`.
 - `herdr` optional nhưng nên có nếu team chạy nhiều agent pane.
+- MCP: `piagent-install` seed preset `core` mặc định (bỏ qua bằng `--no-mcp`). Server connect lazy nên trước lần gọi đầu còn cần Chrome cho `chrome-devtools`, và **Docker đang chạy + `export GITHUB_PERSONAL_ACCESS_TOKEN`** cho `github`. Chi tiết: [MCP và tool policy](mcp-and-tools.md).
 - Git access tới repo platform nếu dùng `git:` package source.
 - OAuth/API access riêng của từng người. Không share token.
 
@@ -40,8 +41,8 @@ Mặc định team dùng stable helper:
 
 ```bash
 node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.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
 ```
@@ -65,7 +66,7 @@ pi install git:github.com/Vt-mmm/piagent
 Full update phải đồng bộ exact Pi host trước, sau đó terminal 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
@@ -77,7 +78,7 @@ Full rollback dùng cùng sequence với `vPREVIOUS`, nhưng exact Pi host phả
 Nếu team publish npm private:
 
 ```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
 pi install npm:@your-scope/platform@x.y.z
 ```
 

package/docs-site/index.html

@@ -798,7 +798,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.0.2 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.1.0 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -927,14 +927,14 @@
             <p class="section-kicker">Quickstart</p>
             <h2>Step by step cho thành viên mới</h2>
             <p class="section-lead">
-              Luồng dưới đây là đường đi chuẩn cho team: chuẩn bị Node.js và Pi Coding Agent, cài Pi Agent Platform từ npm registry theo version đã pin, kiểm tra compatibility, mở repo, chọn profile, bật quyền phù hợp, chạy task, rồi verify bằng command thật. Bản latest chỉ nên dùng cho máy cá nhân hoặc sandbox chấp nhận cập nhật nhanh.
+              Hai lệnh để cài, rồi mở repo, chọn profile, bật quyền phù hợp, chạy task, và verify bằng command thật. Gỡ cũng chỉ hai lệnh khi không dùng nữa.
             </p>
 
             <div class="steps">
               <article class="step">
                 <div>
-                  <h3>Chuẩn bị runtime</h3>
-                  <p>Dùng Node.js 22.19.0 trở lên và Pi Coding Agent <span class="inline-code">0.81.1</span>. Pi Agent Platform <span class="inline-code">v1.0.2</span> đang pin compatibility với runtime này và công bố support matrix theo OS/CPU riêng cho platform helper.</p>
+                  <h3>Cài — hai lệnh</h3>
+                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.0</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>
@@ -963,87 +963,20 @@
                       </tbody>
                     </table>
                   </div>
-                  <div class="command-card">
-                    <header><span>Runtime prerequisites</span><button class="clip-btn" data-clip="node --version&#10;npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;pi --version">Lấy lệnh</button></header>
-                    <pre><code>node --version  # &gt;= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-pi --version</code></pre>
-                  </div>
-                </div>
-              </article>
-              <article class="step">
-                <div>
-                  <h3>Cài Pi Agent Platform có pin</h3>
-                  <p>Đường ngắn nhất là hai lệnh: cài helper từ npm, rồi chạy <span class="inline-code">piagent-setup</span> ngay trong thư mục project. Lệnh đó tự cài đúng Pi host mà release này pin, cài Pi package, khởi tạo <span class="inline-code">.pi/</span> và chạy doctor. Nó cũng cài sẵn MCP baseline và subagents; thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span> nếu không muốn, hoặc <span class="inline-code">--global-only</span> nếu chưa đụng tới project nào.</p>
                   <div class="command-card">
                     <header><span>Hai lệnh</span><button class="clip-btn" data-clip="npm install -g @piagent/platform&#10;piagent-setup">Lấy lệnh</button></header>
                     <pre><code>npm install -g @piagent/platform
 piagent-setup</code></pre>
                   </div>
-                  <p>Vì chạy từ package đã cài, source ghi vào <span class="inline-code">.pi/settings.json</span> là <span class="inline-code">npm:@piagent/platform@&lt;version&gt;</span> — giá trị này có nghĩa như nhau trên máy đồng đội, nên commit được.</p>
-                  <p>Muốn kiểm soát từng lớp thì cài tay: helper trước, rồi dùng helper đó resolve stable tag thành commit SHA và cài Pi package matching. Trong output, <span class="inline-code">currentRelease</span> là version của terminal helper đang chạy. Direct Pi install chỉ dùng khi không cần command <span class="inline-code">piagent-*</span>.</p>
-                  <p>Hai thành phần này lấy từ hai nguồn khác nhau, và đó là chủ ý. Helper là tarball đã publish nên npm verify được provenance attestation gắn với commit build ra nó. Pi package thì dựa vào việc resolve tag thành commit SHA rồi đối chiếu với <span class="inline-code">PIAGENT_EXPECTED_RELEASE_COMMIT</span> — một phép kiểm mà version range của registry không diễn đạt được. Trỏ <span class="inline-code">stable</span> sang npm là bỏ phép kiểm đó chứ không phải thay nó, nên nguồn <span class="inline-code">git:</span> được giữ nguyên. Máy không có quyền Git tới repo này thì dùng channel <span class="inline-code">npm:@piagent/platform@x.y.z</span>.</p>
-                  <div class="command-card">
-                    <header><span>Stable helper install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @piagent/platform@1.0.2&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-                    <pre><code>npm install -g --ignore-scripts @piagent/platform@1.0.2
-piagent-install --stable --dry-run
-piagent-install --stable</code></pre>
-                  </div>
-                  <div class="command-card">
-                    <header><span>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.2">Lấy lệnh</button></header>
-                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.2</code></pre>
-                  </div>
-                </div>
-              </article>
-
-              <article class="step">
-                <div>
-                  <h3>Update hoặc rollback đúng cả ba thành phần</h3>
-                  <p>Full update/rollback phải dùng exact Pi host của release target, đổi npm-global helper, rồi apply stable Pi package từ chính helper đó. Lệnh <span class="inline-code">--version ... --resolve-tag</span> chỉ đổi Pi package và giữ host/helper hiện tại.</p>
-                  <div class="command-card">
-                    <header><span>Full platform target</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-                    <pre><code>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</code></pre>
-                  </div>
-                  <div class="command-card">
-                    <header><span>Pi package only</span><button class="clip-btn" data-clip="piagent-install --version vX.Y.Z --resolve-tag --dry-run&#10;piagent-install --version vX.Y.Z --resolve-tag">Lấy lệnh</button></header>
-                    <pre><code>piagent-install --version vX.Y.Z --resolve-tag --dry-run
-piagent-install --version vX.Y.Z --resolve-tag</code></pre>
-                  </div>
-                </div>
-              </article>
-
-              <article class="step">
-                <div>
-                  <h3>Latest chỉ cho cá nhân/sandbox</h3>
-                  <p>Dùng latest khi muốn nhận thay đổi nhanh trên máy riêng. Khi đưa vào repo/team, đổi sang tag hoặc commit đã review để mọi developer nhận cùng một cấu hình.</p>
+                  <p>Vì chạy từ package đã cài, source ghi vào <span class="inline-code">.pi/settings.json</span> là <span class="inline-code">npm:@piagent/platform@&lt;version&gt;</span> — giá trị này có nghĩa như nhau trên máy đồng đội, nên commit được cho cả team.</p>
+                  <p>Dùng <a href="https://herdr.dev/docs/install/">Herdr</a> thì cài Herdr <strong>trước</strong>: <span class="inline-code">piagent-setup</span> tự cài luôn Herdr Pi integration khi thấy <span class="inline-code">herdr</span> trên <span class="inline-code">PATH</span>, còn không thì bỏ qua kèm cảnh báo — cài Herdr sau phải chạy lại <span class="inline-code">piagent-setup --global-only</span>.</p>
                   <div class="command-card">
-                    <header><span>Personal latest</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent&#10;pi update --extensions">Lấy lệnh</button></header>
-                    <pre><code>pi install git:github.com/Vt-mmm/piagent
-pi update --extensions</code></pre>
-                  </div>
-                </div>
-              </article>
-
-              <article class="step">
-                <div>
-                  <h3>Gỡ cài đặt khi không dùng nữa</h3>
-                  <p><span class="inline-code">piagent-uninstall</span> mặc định chỉ in ra sẽ gỡ những gì rồi thoát; phải thêm <span class="inline-code">--apply</span> nó mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào. Mặc định chỉ gỡ Pi package của platform; add-on, Pi host và state trong project đều là opt-in.</p>
-                  <div class="command-card">
-                    <header><span>Gỡ</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply&#10;npm uninstall -g @piagent/platform">Lấy lệnh</button></header>
-                    <pre><code>piagent-uninstall                                     # chỉ báo cáo
-piagent-uninstall --apply                             # gỡ Pi package của platform
-piagent-uninstall --apply --with-addons --with-host   # + add-on và Pi host
-piagent-uninstall --apply --project /path/to/project  # + state trong project
-npm uninstall -g @piagent/platform                    # helper npm-global</code></pre>
-                  </div>
-                  <p>Nó gỡ theo những gì đang đăng ký trong Pi settings chứ không theo những gì bản hiện tại cài, nên package do release cũ đăng ký vẫn ra được.</p>
-                  <div class="callout ok-callout">
-                    <strong>Không bao giờ bị xoá</strong>
-                    <p>Credential, trust, session, todo và <span class="inline-code">.pi/memory/</span> được giữ nguyên ở mọi tổ hợp cờ — đó là dữ liệu của người dùng, không phải state của platform. Các file sinh từ template rồi sửa tiếp như <span class="inline-code">AGENTS.md</span>, <span class="inline-code">.pi/settings.json</span>, <span class="inline-code">project-context.md</span> chỉ được liệt kê để tự quyết. Với <span class="inline-code">.pi/settings.json</span>, chỉ đúng entry trỏ tới platform bị bỏ khỏi <span class="inline-code">packages</span>.</p>
+                    <header><span>Herdr (tuỳ chọn, cài trước)</span><button class="clip-btn" data-clip="brew install herdr">Lấy lệnh</button></header>
+                    <pre><code>brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS hoặc Linux</code></pre>
                   </div>
+                  <p>Bản <span class="inline-code">curl</span> chạy script tải về lúc cài; muốn kiểm tra được thì dùng <span class="inline-code">brew</span> hoặc tải từ <a href="https://github.com/ogulcancelik/herdr/releases">GitHub releases</a>. Herdr stable hỗ trợ macOS và Linux, Windows mới ở mức preview.</p>
+                  <p>Rollout pin từng bước, update, rollback, và channel latest cho máy cá nhân nằm trong <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/release-install-policy.md">release &amp; install policy</a>.</p>
                 </div>
               </article>
 
@@ -1056,6 +989,7 @@ npm uninstall -g @piagent/platform                    # helper npm-global</code>
                     <pre><code>cd /path/to/project
 pi</code></pre>
                   </div>
+                  <p>Cần nhiều agent chạy song song thì gõ <span class="inline-code">herdr</span> thay cho <span class="inline-code">pi</span>, mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal và session — nó không phải security boundary, gate vẫn nằm ở Pi extension và OAuth vẫn login trong Pi. Cách dựng pane: <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/herdr-workflow.md">Herdr workflow</a>.</p>
                 </div>
               </article>
 
@@ -1110,18 +1044,32 @@ pi</code></pre>
               <article class="step">
                 <div>
                   <h3>Verify trước khi handoff</h3>
-                  <p>Final gate chỉ tin kết quả command đã chạy thật, exit 0, và khớp verify plan. Với setup team, chạy doctor và smoke test sau khi pin hoặc nâng version.</p>
+                  <p>Final gate chỉ tin kết quả command đã chạy thật, exit 0, và khớp verify plan. Sau khi pin hoặc nâng version, chạy doctor trên project:</p>
                   <div class="command-card">
-                    <header><span>Doctor + smoke</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project --strict-share&#10;npm run smoke&#10;npm run verify&#10;npm test&#10;npm run typecheck">Lấy lệnh</button></header>
-                    <pre><code>piagent-doctor /path/to/project --strict-share
-# in piagent source repo:
-npm run smoke
-npm run verify
-npm test
-npm run typecheck</code></pre>
+                    <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor">Lấy lệnh</button></header>
+                    <pre><code>piagent-doctor</code></pre>
                   </div>
+                  <p>Người phát triển chính platform còn có <span class="inline-code">npm run verify</span> trong source repo; chi tiết ở <a href="https://github.com/Vt-mmm/piagent/blob/main/CONTRIBUTING.md">CONTRIBUTING</a>.</p>
                 </div>
               </article>
+
+              <article class="step">
+                <div>
+                  <h3>Gỡ cài đặt khi không dùng nữa</h3>
+                  <p><span class="inline-code">piagent-uninstall</span> mặc định chỉ in ra sẽ gỡ những gì rồi thoát; phải thêm <span class="inline-code">--apply</span> nó mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào. Mặc định chỉ gỡ Pi package của platform; add-on, Pi host và state trong project đều là opt-in.</p>
+                  <div class="command-card">
+                    <header><span>Gỡ — hai lệnh</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply">Lấy lệnh</button></header>
+                    <pre><code>piagent-uninstall
+piagent-uninstall --apply</code></pre>
+                  </div>
+                  <p>Add-on, Pi host, state trong project và helper npm-global đều tách riêng và là opt-in — <span class="inline-code">piagent-uninstall --help</span> liệt kê đủ. Nó gỡ theo những gì đang đăng ký trong Pi settings chứ không theo những gì bản hiện tại cài, nên package do release cũ đăng ký vẫn ra được.</p>
+                  <div class="callout ok-callout">
+                    <strong>Không bao giờ bị xoá</strong>
+                    <p>Credential, trust, session, todo và <span class="inline-code">.pi/memory/</span> được giữ nguyên ở mọi tổ hợp cờ — đó là dữ liệu của người dùng, không phải state của platform. Các file sinh từ template rồi sửa tiếp như <span class="inline-code">AGENTS.md</span>, <span class="inline-code">.pi/settings.json</span>, <span class="inline-code">project-context.md</span> chỉ được liệt kê để tự quyết. Với <span class="inline-code">.pi/settings.json</span>, chỉ đúng entry trỏ tới platform bị bỏ khỏi <span class="inline-code">packages</span>.</p>
+                  </div>
+                </div>
+              </article>
+
             </div>
           </section>
 
@@ -1504,8 +1452,8 @@ npm run typecheck</code></pre>
                 <pre><code>piagent-setup --mcp-preset core --subagents-preset safe</code></pre>
               </article>
               <article class="command-card">
-                <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-                <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+                <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+                <pre><code>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</code></pre>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -78,8 +78,8 @@
     }
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.81.1",
-    "@earendil-works/pi-coding-agent": "0.81.1",
+    "@earendil-works/pi-ai": "0.82.0",
+    "@earendil-works/pi-coding-agent": "0.82.0",
     "typebox": "1.1.38"
   },
   "peerDependenciesMeta": {
@@ -116,6 +116,7 @@
     "audit:runtime": "bash scripts/audit-runtime-host.sh",
     "release:identity": "node scripts/verify-release-identity.mjs",
     "vercel:preflight": "node scripts/verify-vercel-link.mjs",
+    "site:check": "node scripts/check-published-site.mjs",
     "smoke": "bash scripts/runtime-policy-smoke.sh",
     "usage": "bash scripts/pi-session-stats.sh",
     "auto": "bash scripts/pi-auto.sh",

package/packages/piagent-core/README.md

@@ -64,6 +64,7 @@ Inside Pi, slash commands can switch the current session without writing the pro
 - `piagent_project_onboarding_record`
 - `piagent_task_start`
 - `piagent_source_checkout`
+- `piagent_document_read` — reads `.md`/`.txt`/`.csv`/`.json`/`.yaml`/`.pdf`/`.docx` from the project or a granted `additionalReadRoots` directory; read-only, and `protectedPaths` still wins
 - `piagent_context_record`
 - `piagent_verify_record` — records verify evidence only after matching an observed bash tool result after task start
 - `piagent_trace_record`
@@ -108,7 +109,7 @@ pi install git:github.com/Vt-mmm/piagent
 
 Use `git:github.com/Vt-mmm/piagent@vX.Y.Z` when pinning a reproducible project package source.
 
-Runtime support follows the root release matrix: Node.js `>=22.19.0`, Pi Coding Agent `0.81.1`, verified rollout on macOS Apple Silicon + Bash and Linux x64 + Bash, supported-target smoke verification for macOS Intel/Linux ARM64, no native Windows team rollout target yet, and WSL2 experimental.
+Runtime support follows the root release matrix: Node.js `>=22.19.0`, Pi Coding Agent `0.82.0`, verified rollout on macOS Apple Silicon + Bash and Linux x64 + Bash, supported-target smoke verification for macOS Intel/Linux ARM64, no native Windows team rollout target yet, and WSL2 experimental.
 
 ## Project profile