@piagent/platform 1.1.9 → 1.2.1

package/docs-site/content/runtime.html

@@ -0,0 +1,45 @@
+<section class="section">
+
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Setup global</span><button class="clip-btn" data-clip="piagent-setup --mcp-preset core --subagents-preset safe">Lấy lệnh</button></header>
+      <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.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>
+    </article>
+    <article 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>
+    </article>
+    <article class="command-card">
+      <header><span>Init project</span><button class="clip-btn" data-clip="piagent-init /path/to/project">Lấy lệnh</button></header>
+      <pre><code>piagent-init /path/to/project</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project">Lấy lệnh</button></header>
+      <pre><code>piagent-doctor /path/to/project</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Trusted run</span><button class="clip-btn" data-clip="piagent-auto --full-access -p &quot;Run the trusted local benchmark suite.&quot;">Lấy lệnh</button></header>
+      <pre><code>piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
+piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Lấy lệnh</button></header>
+      <pre><code>piagent-capabilities catalog --check
+piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Lấy lệnh</button></header>
+      <pre><code>npm run verify
+npm test
+npm run typecheck</code></pre>
+    </article>
+  </div>
+</section>

package/docs-site/content/scope.html

@@ -0,0 +1,71 @@
+<section class="section">
+  <h2 id="khong-phai-agent-moi">Đây không phải một agent mới</h2>
+  <p>Platform này không có model riêng, không có runtime riêng, không có vòng lặp agent riêng. Nó chạy như extension của Pi và chỉ thêm đúng một thứ: <strong>một cách vận hành cố định</strong> mà mọi repo trong team dùng lại được.</p>
+  <p>Agent coding CLI tổng quát nào cũng đã có sandbox, approval và cơ chế cấu hình theo project. Câu hỏi đáng hỏi không phải "cái nào mạnh hơn" mà là "cái đó cấu hình được, nhưng ai cấu hình, và cấu hình đó có giống nhau giữa 20 repo không".</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr>
+          <th>Hạng mục</th>
+          <th>Agent CLI tổng quát đã có</th>
+          <th>Platform này thêm</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Vai trò</td>
+          <td>Coding agent chạy trên local repo, tự chọn tool và tự chạy lệnh.</td>
+          <td>Lớp governance cho Pi: policy, profile và workflow vận hành được ghi thành file, không nằm trong prompt.</td>
+        </tr>
+        <tr>
+          <td>Tuỳ biến team</td>
+          <td>File hướng dẫn, settings, permission, hooks, skills, MCP — mỗi repo tự khai.</td>
+          <td>Adapter profile, base policy, command guard, capability pack, docs và scripts — khai một lần, <span class="inline-code">piagent-init</span> rải sang repo mới.</td>
+        </tr>
+        <tr>
+          <td>Quyền chạy</td>
+          <td>Sandbox ở mức OS hoặc process, approval theo lượt, giới hạn thư mục làm việc.</td>
+          <td>Ba mode đặt tên sẵn — <span class="inline-code">read-only</span>, <span class="inline-code">workspace-write</span>, <span class="inline-code">trusted-full-access</span> — đổi bằng một command, không sửa file nào.</td>
+        </tr>
+        <tr>
+          <td>Bảo mật secret</td>
+          <td>Sandbox, approval và network policy ở lớp dưới tool.</td>
+          <td>Policy ở lớp application, chạy sau khi tool được gọi: protected path, shell check, symlink alias, output redaction, integrity lock.</td>
+        </tr>
+        <tr>
+          <td>Điểm mạnh riêng</td>
+          <td>Trải nghiệm agent hoàn chỉnh, hệ sinh thái tool rộng.</td>
+          <td>Tính lặp lại: mọi repo cùng profile, cùng guard, cùng kỷ luật verify — và khác biệt thì thấy được vì nó nằm trong file.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="hai-lop-khong-thay-the-nhau">Hai lớp không thay thế nhau</h2>
+  <p>Sandbox của host chặn ở mức process: tiến trình không mở được file ngoài phạm vi cho phép. Guard của platform chặn ở mức lời gọi tool: nó đọc được <em>tham số</em> mà agent định dùng, nên biết lệnh đang đọc file nào, đang ghi ở đâu, đang gửi gì ra ngoài.</p>
+
+  <div class="split">
+    <div class="card">
+      <h3 id="lop-duoi">Lớp dưới thấy process</h3>
+      <p>Biết một tiến trình đang cố ghi ra ngoài workspace. Không biết tiến trình đó là <span class="inline-code">npm test</span> hay là một script vừa được sinh ra trong lượt này.</p>
+    </div>
+    <div class="card">
+      <h3 id="lop-tren">Lớp trên thấy ý định</h3>
+      <p>Biết tool nào, tham số nào, capability nào. Đủ để chặn <span class="inline-code">.env</span> theo tên, redact token trong output, và từ chối một MCP server mà repo mang theo.</p>
+    </div>
+  </div>
+
+  <div class="callout">
+    <strong>Bỏ lớp nào cũng hụt</strong>
+    <p>Guard ở lớp application không thay được sandbox: một tiến trình đã chạy rồi thì guard không với tới nữa. Ngược lại sandbox không biết <span class="inline-code">.env</span> khác gì <span class="inline-code">.env.example</span>. Platform này giả định lớp dưới vẫn bật.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="khi-nao-khong-can">Khi nào không cần</h2>
+  <p>Một repo, một người, không secret nào đáng kể, không có ai khác phải làm theo cùng cách — thì cấu hình sẵn của Pi là đủ, và thêm một lớp nữa chỉ tốn thời gian đọc.</p>
+  <p>Platform này bắt đầu có lãi khi số repo đủ nhiều để không ai nhớ nổi repo nào đang mở quyền gì, hoặc khi câu "đã verify chưa" cần một câu trả lời giống nhau ở mọi repo.</p>
+</section>

package/docs-site/content/security.html

@@ -0,0 +1,51 @@
+<section class="section">
+
+  <div class="grid cols-2">
+    <article class="card">
+      <h3 id="protected-paths">Protected paths</h3>
+      <p>Chặn đọc/ghi qua controlled tools đối với file như <span class="inline-code">.env</span>, <span class="inline-code">auth.json</span>, local trust files, profile lock và settings nhạy cảm.</p>
+    </article>
+    <article class="card">
+      <h3 id="shell-hardening">Shell hardening</h3>
+      <p>Guard dựa vào shell parser và rule cho command được kiểm soát để bắt glob, brace, redirection, bare-word symlink và xargs composition trước khi shell mở rộng runtime.</p>
+    </article>
+    <article class="card">
+      <h3 id="secret-redaction">Secret redaction</h3>
+      <p>Tool output text đi qua redactor để che token, provider keys, secret keyword patterns và giá trị nhạy cảm phổ biến. Benchmark hiện là synthetic/internal và model vẫn đang hoàn thiện.</p>
+    </article>
+    <article class="card">
+      <h3 id="capability-lock">Capability lock</h3>
+      <p>Pack lock có digest và tamper detection. Lock hỏng thì fail-closed, không tự nới quyền.</p>
+    </article>
+    <article class="card">
+      <h3 id="human-action-gate">Human-action gate</h3>
+      <p>Destructive hoặc external-provider action vẫn cần operator xác nhận rõ, kể cả khi full-access đang bật. Gate áp dụng cho direct tool, MCP proxy đã decode và các shell form như GitHub CLI write hoặc HTTP non-GET.</p>
+    </article>
+    <article class="card">
+      <h3 id="verify-evidence">Verify evidence</h3>
+      <p>Handoff hoàn tất cần bằng chứng verify từ bash result đã quan sát, không nhận câu trả lời “đã test” suông.</p>
+    </article>
+  </div>
+
+  <div class="callout">
+    <strong>Ranh giới quan trọng</strong>
+    <p>Guard phụ thuộc vào tool path, controlled tools và shell parser mà platform quan sát được. Nó không ngăn một process khác chạy cùng quyền OS đọc/ghi ngoài guard, và không thay thế sandbox của hệ điều hành.</p>
+    <ul>
+      <li>Có thể bị ảnh hưởng bởi symlink, encoding, nested payload, shell expansion hoặc tool mới chưa được policy hoá.</li>
+      <li>Redaction là backstop giảm rò rỉ, không phải giấy phép để đưa secret thật vào prompt/output.</li>
+      <li>Workload không tin cậy cần container/VM với giới hạn filesystem, process, network và credential.</li>
+    </ul>
+  </div>
+
+  <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 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. 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>

package/docs-site/content/team.html

@@ -0,0 +1,23 @@
+<section class="section">
+
+  <div class="split">
+    <article class="card">
+      <h3 id="viec-nen-lam">Việc nên làm</h3>
+      <p>Chạy <span class="inline-code">/onboard-project</span>, áp <span class="inline-code">/profile auto</span>, dùng workflow command, verify thật và ghi blockers rõ ràng.</p>
+    </article>
+    <article class="card">
+      <h3 id="viec-nen-tranh">Việc nên tránh</h3>
+      <p>Đưa token, auth file, cache, session, private examples hoặc business logic riêng vào core package public.</p>
+    </article>
+  </div>
+
+  <div class="callout ok-callout">
+    <strong>Chuẩn handoff</strong>
+    <p>Final response nên nói ngắn: đã đổi gì, verify nào đã chạy, có dùng subagent không, và còn rủi ro hoặc next step nào cần người review.</p>
+  </div>
+
+  <div class="callout">
+    <strong>Release docs gate</strong>
+    <p>Version docs mới chỉ được promote lên Vercel sau khi tag-triggered CI pass và stable dry-run resolve đúng commit SHA. Phải promote đúng tagged commit, không chèn merge commit hay docs-only edit khác. Domain canonical là <span class="inline-code">piagent.io.vn</span>; apex phải là Vercel primary và <span class="inline-code">www</span> redirect về apex.</p>
+  </div>
+</section>

package/docs-site/content/workflows.html

@@ -0,0 +1,47 @@
+<section class="section">
+  <div class="callout ok-callout">
+    <strong>Git trong Pi Agent</strong>
+    <p>Không có namespace <span class="inline-code">/git</span> riêng. Dùng <span class="inline-code">/commit</span> để commit local đã review, dùng <span class="inline-code">/pr</span> để chuẩn bị PR. Các hành động như <span class="inline-code">git push</span> hoặc stage rộng <span class="inline-code">git add -A</span> vẫn cần operator xác nhận.</p>
+  </div>
+
+  <div class="callout">
+    <strong>Solo-first orchestration</strong>
+    <p>Dùng <span class="inline-code">/piagent-orchestration</span> để xem mode, max subagents, review lenses, Field Guide và writer policy. Mặc định parent agent tự làm chính; subagents chỉ dùng khi scout, planning hoặc review có lane độc lập đáng token.</p>
+  </div>
+
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Implementation bounded</span><button class="clip-btn" data-clip="/task Fix the failing checkout test and verify.">Lấy lệnh</button></header>
+      <pre><code>/task Fix the failing checkout test and verify.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Read-only scout</span><button class="clip-btn" data-clip="/scout Map the auth flow and risk areas.">Lấy lệnh</button></header>
+      <pre><code>/scout Map the auth flow and risk areas.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Plan trước khi code</span><button class="clip-btn" data-clip="/plan Add multi-tenant billing support.">Lấy lệnh</button></header>
+      <pre><code>/plan Add multi-tenant billing support.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Review diff</span><button class="clip-btn" data-clip="/review">Lấy lệnh</button></header>
+      <pre><code>/review</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Commit local có guard</span><button class="clip-btn" data-clip="/commit &quot;feat: add guarded git workflow&quot;">Lấy lệnh</button></header>
+      <pre><code>/commit "feat: add guarded git workflow"</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Chuẩn bị pull request</span><button class="clip-btn" data-clip="/pr &quot;Prepare PR for guarded git workflow&quot;">Lấy lệnh</button></header>
+      <pre><code>/pr "Prepare PR for guarded git workflow"</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Backend spec sang frontend</span><button class="clip-btn" data-clip="/be-to-fe Implement frontend support for the new user status endpoint.">Lấy lệnh</button></header>
+      <pre><code>/profile be-readonly-fe
+/be-to-fe Implement frontend support for the new user status endpoint.</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Cải thiện platform</span><button class="clip-btn" data-clip="/platform-improve Harden command docs and run verification.">Lấy lệnh</button></header>
+      <pre><code>/platform-improve Harden command docs and run verification.</code></pre>
+    </article>
+  </div>
+</section>