@piagent/platform 1.40.0 → 1.42.0

package/docs-site/content/quickstart.html

@@ -1,143 +1,108 @@
 <section class="section">
-
   <div class="steps">
     <article class="step">
-      <div>
-        <h3 id="cai-hai-lenh">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 host mà release hiện tại đ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>
-              <tr>
-                <th>Runtime</th>
-                <th>Trạng thái rollout</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td>macOS Apple Silicon + Bash</td>
-                <td>Đã verify cho release này.</td>
-              </tr>
-              <tr>
-                <td>Linux x64 + Bash</td>
-                <td>Đã verify trong CI.</td>
-              </tr>
-              <tr>
-                <td>macOS Intel / Linux ARM64 + Bash</td>
-                <td>Supported target; chạy doctor + smoke test trước khi rollout rộng.</td>
-              </tr>
-              <tr>
-                <td>Windows (WSL2)</td>
-                <td>Một lệnh PowerShell cài tất cả: xem <a href="/windows">Cài trên Windows</a>. Chạy thẳng trên Windows mới là bản xem trước cho chế độ cá nhân.</td>
-              </tr>
-            </tbody>
-          </table>
+      <h3 id="cai-dat">Cài đặt</h3>
+      <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi trước: <code>piagent-setup</code> tự cài đúng bản Pi mà release này pin, khởi tạo <code>.pi/</code>, cài MCP baseline và subagent, rồi chạy doctor.</p>
+      <div class="tabs" data-tabs="os">
+        <div class="tab-list" role="tablist" aria-label="Hệ điều hành">
+          <button type="button" role="tab" data-tab="macos" aria-selected="true">{{icon:apple}} macOS · Linux</button>
+          <button type="button" role="tab" data-tab="windows" aria-selected="false" tabindex="-1">{{icon:windows}} Windows</button>
         </div>
-        <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
+        <div class="tab-panel" data-panel="macos">
+          <div class="command-card">
+            <header><span>Chạy trong thư mục project</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>
         </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>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>
-
-    <article class="step">
-      <div>
-        <h3 id="mo-repo-du-an">Mở repo dự án</h3>
-        <p>Chạy Pi từ thư mục repo. Với repo đã tin cậy, dùng wrapper trusted-run khi cần tự động hoá có kiểm soát.</p>
-        <div class="command-card">
-          <header><span>Start</span><button class="clip-btn" data-clip="cd /path/to/project && pi">Lấy lệnh</button></header>
-          <pre><code>cd /path/to/project
-pi</code></pre>
+        <div class="tab-panel" data-panel="windows" hidden>
+          <div class="command-card">
+            <header><span>PowerShell</span><button class="clip-btn" data-clip="irm https://raw.githubusercontent.com/Vt-mmm/agentwatch/main/windows/setup.ps1 | iex">Lấy lệnh</button></header>
+            <pre><code>irm https://raw.githubusercontent.com/Vt-mmm/agentwatch/main/windows/setup.ps1 | iex</code></pre>
+          </div>
+          <p>Cài WSL2, Ubuntu, Piagent và Agent Watch. Chi tiết ở <a href="/windows">Cài trên Windows</a>.</p>
         </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>
+      <p>Bỏ bớt phần cài thêm bằng <code>--no-mcp</code>, <code>--no-subagents</code>, <code>--no-herdr</code> hoặc <code>--global-only</code>.</p>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="onboard-context">Cho agent đọc project</h3>
-        <p>Ở repo mới, nhờ agent đọc project (chỉ đọc) và ghi lại project context vào <span class="inline-code">.pi/</span>. Không cần lệnh riêng: nói bằng lời thường.</p>
-        <div class="command-card">
-          <header><span>Đọc project</span><button class="clip-btn" data-clip="Đọc project này (chỉ đọc) và ghi lại project context.">Lấy lệnh</button></header>
-          <pre><code>Đọc project này (chỉ đọc) và ghi lại project context.</code></pre>
-        </div>
+      <h3 id="mo-project">Mở project</h3>
+      <p>Terminal và dashboard dùng chung một lịch sử. Chế độ công ty mở bằng <code>piagent studio</code> sau khi đã nhập key qua Agent Watch.</p>
+      <div class="command-card">
+        <header><span>Chọn một</span><button class="clip-btn" data-clip="piagent dashboard">Lấy lệnh</button></header>
+        <pre><code>piagent dashboard          # trình duyệt, chế độ cá nhân
+pi                         # Terminal, chế độ cá nhân
+piagent studio --web       # chế độ công ty</code></pre>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="chon-profile-tech">Chọn profile + tech</h3>
-        <p>Dùng <span class="inline-code">/profile setup</span> để mở select option: chọn profile trước, rồi chọn tech theo role. Fullstack sẽ chọn frontend, backend và database.</p>
-        <div class="command-card">
-          <header><span>Profile tech setup</span><button class="clip-btn" data-clip="/profile setup&#10;/profile tech setup fullstack">Lấy lệnh</button></header>
-          <pre><code>/profile setup
-/profile tech setup fullstack</code></pre>
-        </div>
+      <h3 id="doc-project">Cho agent đọc project</h3>
+      <p>Ở repo mới, nhờ agent đọc (chỉ đọc) và ghi project context vào <code>.pi/</code>. Không cần lệnh riêng.</p>
+      <div class="command-card">
+        <header><span>Tin nhắn đầu tiên</span><button class="clip-btn" data-clip="Đọc project này (chỉ đọc) và ghi lại project context.">Lấy lệnh</button></header>
+        <pre><code>Đọc project này (chỉ đọc) và ghi lại project context.</code></pre>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="chon-permission">Chọn permission</h3>
-        <p>Scout thì read-only, code bình thường thì workspace-write, automation tin cậy thì full-access có guard.</p>
-        <div class="command-card">
-          <header><span>Permission</span><button class="clip-btn" data-clip="/permission status&#10;/permission workspace-write">Lấy lệnh</button></header>
-          <pre><code>/permission status
+      <h3 id="profile-va-quyen">Chọn profile và quyền</h3>
+      <p>Profile quyết định file nào được bảo vệ và check nào chạy. Quyền: <code>read-only</code> để khảo sát, <code>workspace-write</code> để code bình thường.</p>
+      <div class="command-card">
+        <header><span>Slash command</span><button class="clip-btn" data-clip="/profile setup&#10;/permission workspace-write">Lấy lệnh</button></header>
+        <pre><code>/profile setup
 /permission workspace-write</code></pre>
-        </div>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="chay-workflow">Chạy workflow</h3>
-        <p>Nói rõ việc và ý định (sửa, chỉ đọc, lập plan) bằng lời thường. Việc nào nặng context thì mở session mới bằng <span class="inline-code">/new</span>.</p>
-        <div class="command-card">
-          <header><span>Giao việc</span><button class="clip-btn" data-clip="Implement thay đổi được yêu cầu rồi chạy test của project.&#10;Review diff hiện tại. Chỉ đọc.">Lấy lệnh</button></header>
-          <pre><code>Implement thay đổi được yêu cầu rồi chạy test của project.
+      <h3 id="giao-viec">Giao việc bằng lời thường</h3>
+      <p>Nói rõ việc và ý định: sửa, chỉ đọc hay lập plan. Việc nặng context thì mở session mới bằng <code>/new</code>.</p>
+      <div class="command-card">
+        <header><span>Ví dụ</span><button class="clip-btn" data-clip="Sửa lỗi phân trang ở /orders rồi chạy test của project.">Lấy lệnh</button></header>
+        <pre><code>Sửa lỗi phân trang ở /orders rồi chạy test của project.
 Review diff hiện tại. Chỉ đọc.</code></pre>
-        </div>
       </div>
     </article>
 
     <article class="step">
-      <div>
-        <h3 id="verify-truoc-khi-handoff">Kiểm tra trước khi giao</h3>
-        <p>Nhờ agent chạy check của project (test, type check, build) và đọc kết quả thật; ở chế độ công ty, Harness tự yêu cầu việc này. Sau khi pin hoặc nâng version, chạy doctor trên project:</p>
-        <div class="command-card">
-          <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>
+      <h3 id="kiem-tra">Kiểm tra cài đặt</h3>
+      <p>Sau khi cài hoặc đổi bản, chạy doctor trên project. Lỗi nào cũng kèm cách sửa.</p>
+      <div class="command-card">
+        <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>
     </article>
+  </div>
+</section>
 
-    <article class="step">
-      <div>
-        <h3 id="go-cai-dat-khi-khong-dung-nua">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>
+<section class="section">
+  <h2 id="ho-tro">Hệ điều hành được hỗ trợ</h2>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Môi trường</th><th>Trạng thái</th></tr></thead>
+      <tbody>
+        <tr><td>macOS Apple Silicon</td><td>Đã kiểm chứng cho release này.</td></tr>
+        <tr><td>Linux x64</td><td>Đã kiểm chứng trong CI.</td></tr>
+        <tr><td>macOS Intel, Linux ARM64</td><td>Hỗ trợ; chạy doctor và smoke test trước khi rollout rộng.</td></tr>
+        <tr><td>Windows (WSL2)</td><td>Cách chạy Piagent trên Windows, cả chế độ cá nhân và công ty.</td></tr>
+        <tr><td>Windows native</td><td>Bản xem trước cho chế độ cá nhân; chưa có <code>piagent-update</code>.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="callout">
+    <strong>Dùng Herdr?</strong>
+    <p>Cài Herdr <em>trước</em> <code>piagent-setup</code> để được cài luôn tích hợp Pi; cài sau thì chạy lại <code>piagent-setup --global-only</code>. Herdr chỉ điều phối terminal, không phải lớp bảo vệ. Xem <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/herdr-workflow.md">Herdr workflow</a>.</p>
+  </div>
+</section>
 
+<section class="section">
+  <h2 id="tiep-theo">Tiếp theo</h2>
+  <div class="card-grid">
+    <a class="doc-card" href="/update"><span class="card-kicker">{{icon:refresh}} Vận hành</span><h3>Cập nhật và gỡ</h3><p>Lên bản mới, pin cho team, rollback, gỡ có xem trước.</p></a>
+    <a class="doc-card" href="/ecosystem"><span class="card-kicker">{{icon:network}} Bắt đầu</span><h3>Hệ sinh thái</h3><p>Khi nào dùng model cá nhân, khi nào dùng Agent Studio.</p></a>
+    <a class="doc-card" href="/permissions"><span class="card-kicker">{{icon:key}} Sử dụng</span><h3>Permission modes</h3><p>Bốn mức quyền và khi nào dùng mức nào.</p></a>
+    <a class="doc-card" href="/mcp"><span class="card-kicker">{{icon:plug}} MCP</span><h3>MCP</h3><p>Preset đã pin, quản lý server và approval gate.</p></a>
   </div>
 </section>

package/docs-site/content/update.html

@@ -0,0 +1,80 @@
+<section class="section">
+  <h2 id="cap-nhat">Cập nhật</h2>
+  <p>Dashboard và Terminal kiểm tra bản mới mỗi giờ. Khi có bản mới, dashboard mở hộp thoại ghi thay đổi gì, với <strong>Cập nhật ngay</strong> và <strong>Để sau</strong> (hỏi lại sau một giờ). Muốn tự chạy thì dùng một lệnh:</p>
+  <div class="command-card">
+    <header><span>Lên bản mới nhất</span><button class="clip-btn" data-clip="piagent-update">Lấy lệnh</button></header>
+    <pre><code>piagent-update</code></pre>
+  </div>
+  <p>Khởi động lại dashboard sau khi cập nhật để giao diện mới có hiệu lực.</p>
+
+  <h3 id="cap-nhat-lam-gi">Lệnh này làm gì, theo thứ tự</h3>
+  <ol>
+    <li>Xác định bản đích và bản Pi mà bản đó pin.</li>
+    <li>Cài đúng Pi host đó, rồi thay helper <code>piagent-update</code>.</li>
+    <li>Kiểm tra version thật trên đĩa trước khi chạy installer.</li>
+    <li>Với <code>--project</code>: migrate state của project và chạy <code>piagent-doctor --strict-share</code>.</li>
+  </ol>
+  <div class="callout">
+    <strong>Không chạy từ git checkout</strong>
+    <p><code>piagent-update</code> từ chối chạy khi package toàn cục là một bản link tới source repo, để không ghi đè code bạn đang sửa.</p>
+  </div>
+
+  <h3 id="tuy-chon">Tuỳ chọn thường dùng</h3>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>Lệnh</th><th>Dùng khi</th></tr></thead>
+      <tbody>
+        <tr><td><code>piagent-update --check</code></td><td>Chỉ xem có bản mới không.</td></tr>
+        <tr><td><code>piagent-update --dry-run</code></td><td>Xem sẽ cài gì, không đổi gì.</td></tr>
+        <tr><td><code>piagent-update --version X.Y.Z</code></td><td>Lên hoặc về đúng một bản.</td></tr>
+        <tr><td><code>piagent-update --project .</code></td><td>Cập nhật và migrate project hiện tại.</td></tr>
+        <tr><td><code>--no-host</code> · <code>--no-package</code> · <code>--no-migrate</code></td><td>Bỏ qua từng bước.</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="pin-cho-team">Pin một bản cho cả team</h2>
+  <p>Khi rollout cho team, cài đúng bản Pi host và đúng bản platform, rồi chạy installer ở chế độ stable. Bước <code>--dry-run</code> in ra những gì sẽ đổi.</p>
+  <div class="command-card">
+    <header><span>Cài pin theo bản</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@{{piHost}}&#10;npm install -g --ignore-scripts @piagent/platform@{{version}}&#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@{{piHost}}
+npm install -g --ignore-scripts @piagent/platform@{{version}}
+piagent-install --stable --dry-run
+piagent-install --stable</code></pre>
+  </div>
+  <p>Vì cài từ package, <code>.pi/settings.json</code> ghi <code>npm:@piagent/platform@&lt;version&gt;</code>: giá trị giống nhau trên mọi máy, commit được cho cả team. Quy trình đầy đủ ở <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/release-install-policy.md">release &amp; install policy</a>.</p>
+</section>
+
+<section class="section">
+  <h2 id="rollback">Rollback</h2>
+  <p>Rollback là thao tác có chủ đích, không tự động. Về một bản cụ thể bằng cùng lệnh cập nhật:</p>
+  <div class="command-card">
+    <header><span>Về bản trước</span><button class="clip-btn" data-clip="piagent-update --version X.Y.Z --dry-run&#10;piagent-update --version X.Y.Z">Lấy lệnh</button></header>
+    <pre><code>piagent-update --version X.Y.Z --dry-run
+piagent-update --version X.Y.Z</code></pre>
+  </div>
+  <p>Chỉ muốn đổi Pi package mà giữ host: <code>piagent-install --version vX.Y.Z --resolve-tag</code>. Sau khi về bản cũ, chạy <code>piagent-doctor</code> trên project.</p>
+</section>
+
+<section class="section">
+  <h2 id="go-cai-dat">Gỡ cài đặt</h2>
+  <p><code>piagent-uninstall</code> mặc định chỉ in ra sẽ gỡ gì rồi thoát. Thêm <code>--apply</code> mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào.</p>
+  <div class="command-card">
+    <header><span>Xem trước, rồi gỡ</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
+npm uninstall -g @piagent/platform</code></pre>
+  </div>
+  <p>Add-on, Pi host và state trong project là opt-in: <code>--with-addons</code>, <code>--with-host</code>, <code>--project &lt;path&gt;</code>.</p>
+  <div class="callout ok-callout">
+    <strong>Không bao giờ bị xoá</strong>
+    <p>Credential, trust, session, todo và <code>.pi/memory/</code> được giữ ở mọi tổ hợp cờ. File sinh từ template rồi đã sửa (<code>AGENTS.md</code>, <code>.pi/settings.json</code>) chỉ được liệt kê để bạn tự quyết.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="windows">Trên Windows</h2>
+  <p>Chạy lại đúng lệnh PowerShell đã dùng để cài: nó cập nhật WSL, Piagent và Agent Watch. Xem <a href="/windows">Cài trên Windows</a>.</p>
+</section>