@piagent/platform 1.0.1 → 1.1.0

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.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
 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.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
 ```
@@ -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,12 +78,26 @@ 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
 ```
 
 Không cần chạy bash để set profile cho từng project.
 
+### Rời platform
+
+Thành viên rời team hoặc máy không dùng platform nữa thì gỡ bằng `piagent-uninstall`. Mặc định nó chỉ báo cáo; `--apply` mới thực hiện:
+
+```bash
+piagent-uninstall
+piagent-uninstall --apply
+piagent-uninstall --apply --with-addons --with-host    # gỡ luôn add-on và Pi host
+piagent-uninstall --apply --project /path/to/project   # gỡ state platform trong project
+npm uninstall -g @piagent/platform
+```
+
+Credential, trust, session, todo và `.pi/memory/` không bị xoá ở bất kỳ tổ hợp cờ nào. `.pi/settings.json` chỉ mất đúng entry trỏ tới platform. Chi tiết trong [release/install policy](release-install-policy.md).
+
 ## Bước 2 — mở project và login OAuth
 
 ```bash

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.1 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 bằng release tag đã 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.1</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>
@@ -964,58 +964,19 @@
                     </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>Team nên cài npm-global 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>
-                  <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.1&#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.1
-piagent-install --stable --dry-run
-piagent-install --stable</code></pre>
+                    <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 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>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.1">Lấy lệnh</button></header>
-                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.1</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>
-                  <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>
+                    <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>
 
@@ -1028,6 +989,7 @@ pi update --extensions</code></pre>
                     <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>
 
@@ -1082,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>
 
@@ -1178,12 +1154,14 @@ npm run typecheck</code></pre>
 
             <div class="callout">
               <strong>Redaction cần kiểm toán độc lập</strong>
-              <p>Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Dự án công khai <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model và attack-vector map</a>; phạm vi OS/shell rộng hơn, parser fuzzing, third-party audit, signed provenance và LTS vẫn là các mức bảo đảm cao hơn chưa được claim.</p>
+              <p>Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Dự án công khai <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model và attack-vector map</a>; phạm vi OS/shell rộng hơn, parser fuzzing, third-party audit và LTS vẫn là các mức bảo đảm cao hơn chưa được claim. Signed provenance thì đã có: mỗi bản publish lên npm mang attestation ký qua sigstore từ GitHub Actions, buộc tarball về đúng commit và workflow tạo ra nó.</p>
             </div>
 
             <div class="callout">
               <strong>Dependency gate tách hai lớp</strong>
-              <p>Release kiểm toán riêng dependency tree nhỏ của terminal helper và cây exact Pi host + pinned add-on. Gate hiện có 0 high/critical; npm vẫn báo 11 moderate dependency paths thuộc hai advisory upstream: encoded-backslash path traversal trên Windows trong Hono adapter và protobuf parser DoS. Native Windows/WSL2 chưa nằm trong matrix rollout team, nhưng dự án vẫn theo dõi cả hai thay vì gọi runtime là “0 vulnerability”.</p>
+              <p>Release kiểm toán riêng dependency tree nhỏ của terminal helper và cây exact Pi host + pinned add-on. Helper tree hiện sạch hoàn toàn. Cây Pi host có 1 high và 11 moderate, và dự án nói thẳng con số đó thay vì gọi runtime là “0 vulnerability”.</p>
+              <p>Bản high là <span class="inline-code">GHSA-mh99-v99m-4gvg</span> trong <span class="inline-code">brace-expansion</span> — DoS, không leo quyền, không lộ dữ liệu. Repo này không sửa được: Pi host publish kèm <span class="inline-code">npm-shrinkwrap.json</span> ghim version dính lỗi, mà shrinkwrap đã publish thì thắng <span class="inline-code">overrides</span> của consumer. Mọi bản Pi đã phát hành đều dính một advisory brace-expansion, nên pin bản cũ chỉ đổi lỗi này lấy lỗi khác. Vì vậy gate miễn trừ đúng một advisory có tên, kèm lý do ghi trong mã nguồn, và tự đỏ lại khi hết hạn rà soát <span class="inline-code">2026-08-25</span> hoặc ngay khi upstream vá xong. Mọi high/critical khác vẫn chặn.</p>
+              <p>11 moderate còn lại thuộc hai advisory upstream: encoded-backslash path traversal trên Windows trong Hono adapter, và protobuf parser DoS. Native Windows/WSL2 chưa nằm trong matrix rollout team, nhưng dự án vẫn theo dõi cả hai.</p>
             </div>
           </section>
 
@@ -1474,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.1",
+  "version": "1.1.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -47,6 +47,7 @@
   "bin": {
     "piagent-setup": "scripts/piagent-cli.mjs",
     "piagent-install": "scripts/piagent-cli.mjs",
+    "piagent-uninstall": "scripts/piagent-cli.mjs",
     "piagent-init": "scripts/piagent-cli.mjs",
     "piagent-doctor": "scripts/piagent-cli.mjs",
     "piagent-benchmark": "scripts/piagent-cli.mjs",
@@ -77,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": {
@@ -93,8 +94,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.13.14",
-    "typescript": "^5.8.3"
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
   },
   "workspaces": [
     "packages/*"
@@ -115,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