@piagent/platform 1.1.9 → 1.2.1

package/docs-site/content/mcp-auth.html

@@ -0,0 +1,76 @@
+<section class="section">
+  <h2 id="khong-giu-token">Platform không giữ token</h2>
+  <p>Token MCP đã có chỗ ở: luồng OAuth thuộc về <span class="inline-code">pi-mcp-adapter</span> — chính nó đăng ký <span class="inline-code">/mcp</span> và <span class="inline-code">/mcp-auth</span>, và chính nó lưu, refresh, thu hồi. Dựng thêm một kho credential nữa để giữ credential của bên thứ ba chỉ tạo thêm một chỗ để token rò ra. Việc của platform vì vậy là <strong>phát hiện và chỉ đường</strong>.</p>
+
+  <pre><code>/mcp-auth figma</code></pre>
+
+  <div class="callout ok-callout">
+    <strong>Ranh giới</strong>
+    <p>Platform không chạy OAuth, không lưu token, không refresh. Nó biết một server <em>cần</em> đăng nhập, nhưng không biết phiên đăng nhập còn hạn hay không — và nó nói đúng như vậy thay vì đoán.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="tu-choi-secret">Secret bị từ chối ngay khi ghi config</h2>
+  <p>MCP config được nhiều client đọc, nằm trong home hoặc trong repo, và ở scope <span class="inline-code">project</span> thì được commit. Một token gõ vào <span class="inline-code">--env</span> sẽ đi tới tất cả những chỗ đó. Nên <span class="inline-code">add</span> từ chối, và nói luôn dạng cần dùng:</p>
+
+  <pre><code>$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
+FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
+written into MCP config. Export it in your shell and reference it instead:
+--env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'</code></pre>
+
+  <div class="split">
+    <div class="card">
+      <h3 id="theo-ten">Theo tên field</h3>
+      <p>Tên chứa <span class="inline-code">token</span>, <span class="inline-code">secret</span>, <span class="inline-code">password</span>, <span class="inline-code">api_key</span>, <span class="inline-code">authorization</span>… thì giá trị bắt buộc phải là tham chiếu biến môi trường.</p>
+    </div>
+    <div class="card">
+      <h3 id="theo-gia-tri">Theo giá trị</h3>
+      <p>Tên không nói gì thì giá trị vẫn được đọc riêng, nên <span class="inline-code">--env CONFIG=ghp_...</span> cũng bị bắt.</p>
+    </div>
+  </div>
+
+  <p>Áp dụng cho cả <span class="inline-code">--header</span>. <span class="inline-code">--url</span> chỉ nhận <span class="inline-code">https</span>, hoặc <span class="inline-code">http</span> khi host là loopback — Figma desktop MCP đúng là trường hợp đó. <span class="inline-code">list</span> và <span class="inline-code">get</span> mask giá trị nhưng in nguyên <span class="inline-code">${VAR}</span>, vì đó là tên biến chứ không phải nội dung.</p>
+</section>
+
+<section class="section">
+  <h2 id="trang-thai">Trạng thái sẵn sàng</h2>
+  <p>Đếm số server không nói được server nào trả lời được. <span class="inline-code">/piagent-mcp doctor</span> phân loại từng cái:</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>State</th><th>Nghĩa</th><th>Cách xử lý</th></tr>
+      </thead>
+      <tbody>
+        <tr><td><span class="inline-code">ready</span></td><td>Đủ điều kiện, gọi được</td><td>—</td></tr>
+        <tr><td><span class="inline-code">needs-env</span></td><td>Config tham chiếu <span class="inline-code">${VAR}</span> mà biến chưa export</td><td>Export biến trong shell profile</td></tr>
+        <tr><td><span class="inline-code">needs-command</span></td><td>Executable không có trên PATH</td><td>Cài, hoặc sửa lại server</td></tr>
+        <tr><td><span class="inline-code">pending-approval</span></td><td>Repo khai server này, chưa ai duyệt trên máy này</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td></tr>
+        <tr><td><span class="inline-code">approval-changed</span></td><td>Đã duyệt nhưng định nghĩa đã đổi</td><td>Đọc lại rồi duyệt lại</td></tr>
+        <tr><td><span class="inline-code">rejected</span></td><td>Đã từ chối cho project này</td><td><span class="inline-code">reset</span> nếu đổi ý</td></tr>
+        <tr><td><span class="inline-code">disabled</span></td><td>Tắt bằng <span class="inline-code">disable</span></td><td><span class="inline-code">/piagent-mcp enable &lt;name&gt;</span></td></tr>
+        <tr><td><span class="inline-code">oauth</span></td><td>Đăng nhập do Pi giữ</td><td><span class="inline-code">/mcp-auth &lt;name&gt;</span> nếu chưa login</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <p>Chỉ báo cái biết chắc. <span class="inline-code">needs-env</span> in ra <strong>tên biến</strong>, không bao giờ in giá trị.</p>
+
+  <p>Trong session là <span class="inline-code">/piagent-mcp doctor</span> — cùng báo cáo, và remedy in ra dạng slash command vì đó là thứ chạy được ngay tại chỗ. Ngoài terminal:</p>
+
+  <pre><code>$ piagent-mcp doctor
+OK   context7 (global): ready
+OK   chrome-devtools (global): ready
+NEED github (global): GITHUB_PERSONAL_ACCESS_TOKEN is referenced but not set
+       -> export GITHUB_PERSONAL_ACCESS_TOKEN=... in your shell profile
+NEED docker: installed but the daemon is not responding
+       -> start Docker Desktop, then re-run piagent-mcp doctor</code></pre>
+
+  <div class="callout">
+    <strong>Vì sao <span class="inline-code">oauth</span> không phải lỗi</strong>
+    <p>Nó không xuất hiện trong notice đầu session. Platform không phân biệt được đã login hay chưa, nên báo mỗi session sẽ thành nhiễu và hết được đọc. Notice chỉ nêu những state chặn chắc chắn; tắt bằng <span class="inline-code">PIAGENT_NO_MCP_NOTICE=1</span>.</p>
+  </div>
+
+  <p><span class="inline-code">doctor</span> chạy thêm <span class="inline-code">docker info</span> — chậm, nên chỉ có ở doctor chứ không ở session start. <span class="inline-code">piagent-doctor</span> cũng đưa các state chặn vào <span class="inline-code">warnings</span>.</p>
+</section>

package/docs-site/content/mcp-servers.html

@@ -0,0 +1,111 @@
+<section class="section">
+  <h2 id="hai-be-mat">Hai bề mặt, chọn theo chỗ đang đứng</h2>
+  <p>Trong session Pi thì gõ <strong>slash command</strong>. Ngoài terminal thì gõ <strong>CLI</strong>. Cùng một dữ liệu, cùng một cách đọc trạng thái — khác nhau ở chỗ ai chạy.</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Việc</th><th>Trong session</th><th>Trong terminal</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>Mở menu</td><td><span class="inline-code">/piagent-mcp</span></td><td>—</td></tr>
+        <tr><td>Xem toàn bộ server + state</td><td><span class="inline-code">/piagent-mcp status</span></td><td><span class="inline-code">piagent-mcp list</span></td></tr>
+        <tr><td>Chi tiết một server</td><td><span class="inline-code">/piagent-mcp get &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp get &lt;name&gt;</span></td></tr>
+        <tr><td>Thiếu gì để chạy được</td><td><span class="inline-code">/piagent-mcp doctor</span></td><td><span class="inline-code">piagent-mcp doctor</span></td></tr>
+        <tr><td>Duyệt server của repo</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp approve &lt;name&gt;</span></td></tr>
+        <tr><td>Bật / tắt</td><td><span class="inline-code">/piagent-mcp enable|disable &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp enable|disable &lt;name&gt;</span></td></tr>
+        <tr><td>Thêm, xoá, preset</td><td>—</td><td><span class="inline-code">piagent-mcp add|remove|--preset</span></td></tr>
+        <tr><td>Trạng thái kết nối, OAuth</td><td><span class="inline-code">/mcp</span>, <span class="inline-code">/mcp-auth</span></td><td>—</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div class="callout ok-callout">
+    <strong>Vì sao slash command chứ không phải gõ CLI trong session</strong>
+    <p>Gõ <span class="inline-code">piagent-mcp list</span> giữa session là nhờ model chạy bash, đọc output rồi thuật lại — ba lượt model cho một câu hỏi mà chính process này trả lời được từ file nó đã đọc. Slash command do Pi dispatch thẳng tới handler, <strong>không đi qua model</strong>: không tốn token, không diễn giải lại, và cùng một câu hỏi luôn ra cùng một câu trả lời.</p>
+  </div>
+
+  <div class="callout">
+    <strong>Thêm server vẫn ở terminal</strong>
+    <p><span class="inline-code">add</span> mang theo shell quoting, tham chiếu <span class="inline-code">${VAR}</span> và một command line sau <span class="inline-code">--</span>. Ba thứ đó đã có một bộ parse đúng là chính shell; viết lại nó bên trong slash command chỉ tạo ra bộ parse thứ hai, tệ hơn. Vì vậy ranh giới là: đọc trạng thái thì ở trong session, ghi định nghĩa server thì ở terminal. Gọi <span class="inline-code">/piagent-mcp add</span> sẽ in ra đúng lệnh terminal cần chạy chứ không đoán.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="lenh">Lệnh</h2>
+
+  <div class="command-grid">
+    <article class="command-card">
+      <h3 id="trong-session">Trong session</h3>
+      <p>Không tham số là menu. Biết rồi thì gõ thẳng — Tab auto-complete cả subcommand lẫn tên server.</p>
+      <pre><code>/piagent-mcp                 menu
+/piagent-mcp status          bảng đầy đủ
+/piagent-mcp get sentry
+/piagent-mcp doctor
+/piagent-mcp approve internal</code></pre>
+    </article>
+
+    <article class="command-card">
+      <h3 id="them-server">Thêm server</h3>
+      <p><span class="inline-code">--url</span> cho server remote, <span class="inline-code">--</span> rồi command cho server chạy local. Chạy ở terminal.</p>
+      <pre><code>piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
+piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp</code></pre>
+    </article>
+
+    <article class="command-card">
+      <h3 id="xem">Xem</h3>
+      <p><span class="inline-code">list</span> cho toàn bộ server nhìn thấy được từ project hiện tại, kèm state. <span class="inline-code">get</span> cho chi tiết một server.</p>
+      <pre><code>piagent-mcp list
+piagent-mcp get sentry</code></pre>
+    </article>
+
+    <article class="command-card">
+      <h3 id="tat-xoa">Tắt và xoá</h3>
+      <p><span class="inline-code">disable</span> giữ nguyên định nghĩa, chỉ ngừng dùng. <span class="inline-code">remove</span> xoá hẳn khỏi scope.</p>
+      <pre><code>piagent-mcp disable sentry
+piagent-mcp enable sentry
+piagent-mcp remove sentry --scope global</code></pre>
+    </article>
+
+    <article class="command-card">
+      <h3 id="preset-lenh">Preset</h3>
+      <p>Seed một nhóm server đã pin sẵn. <span class="inline-code">--replace</span> đưa các server thuộc preset về baseline.</p>
+      <pre><code>piagent-mcp --preset core --scope global --replace
+piagent-mcp --list</code></pre>
+    </article>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="output">Output nói rõ đã sửa file nào</h2>
+  <p>Bốn layer config cùng được đọc, nên câu hỏi đầu tiên khi có gì đó không đúng luôn là "file nào đang có hiệu lực". <span class="inline-code">add</span> trả lời sẵn:</p>
+
+  <pre><code>$ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
+Added local MCP server internal with command: npx -y @acme/internal-mcp in project scope
+File modified: /Users/you/repo/.mcp.json
+This scope is part of the repository, so the server is not usable until approved: piagent-mcp approve internal</code></pre>
+
+  <p><span class="inline-code">list</span> hiển thị dạng bảng, cột <span class="inline-code">STATE</span> cho biết server nào dùng được ngay:</p>
+
+  <pre><code>NAME             SCOPE    TRANSPORT  TARGET                                  STATE
+context7         global   stdio      npx -y @upstash/context7-mcp@3.2.4       ready
+chrome-devtools  global   stdio      npx -y chrome-devtools-mcp@1.6.0 ...     ready
+github           global   stdio      docker run -i --rm -e GITHUB_PERSON...   needs-env
+internal         project  stdio      npx -y @acme/internal-mcp               pending-approval</code></pre>
+</section>
+
+<section class="section">
+  <h2 id="update">Server tự thêm và luồng update</h2>
+  <p>Mỗi lần <span class="inline-code">piagent-update</span> chạy, preset được apply lại với <span class="inline-code">--replace</span>. Vòng merge chỉ đi qua đúng những server ID mà preset sở hữu:</p>
+
+  <div class="split">
+    <div class="card">
+      <h3 id="giu-nguyen">Giữ nguyên</h3>
+      <p>Server có ID riêng — <span class="inline-code">my-internal</span>, <span class="inline-code">sentry</span>, bất cứ tên nào không thuộc preset — sống qua mọi lần update.</p>
+    </div>
+    <div class="card">
+      <h3 id="bi-ghi-de">Bị ghi đè</h3>
+      <p>Sửa tay một server thuộc preset (<span class="inline-code">github</span>, <span class="inline-code">context7</span>…) sẽ bị đưa về baseline ở lần update kế tiếp. Muốn giữ bản riêng thì đặt tên khác.</p>
+    </div>
+  </div>
+</section>

package/docs-site/content/mcp.html

@@ -0,0 +1,120 @@
+<section class="section">
+  <h2 id="bat-dau">Bắt đầu ở đâu</h2>
+  <p>Gõ <span class="inline-code">/piagent-mcp</span> là ra menu — không cần nhớ subcommand nào:</p>
+
+  <pre><code>MCP
+  Servers — 2/3 ready
+  Doctor — 1 need attention          (recommended)
+  Inspect a server
+  Approve a repository server — 1 waiting
+  Turn a server off
+  Add a server
+  All subcommands</code></pre>
+
+  <p>Menu dựng theo đúng thứ project đang có: chưa server nào bị tắt thì không hiện "turn back on", không server nào chờ duyệt thì không hiện "approve". Chọn việc cần server thì nó hỏi tiếp server nào — trừ khi chỉ có đúng một lựa chọn.</p>
+
+  <p>Mọi mục trong menu đều gõ thẳng được:</p>
+
+  <pre><code>/piagent-mcp doctor     cái nào chưa chạy được và còn thiếu gì
+/piagent-mcp status     bảng đầy đủ
+/mcp                    trạng thái kết nối live, do adapter giữ
+/mcp-auth &lt;name&gt;        đăng nhập OAuth cho một server</code></pre>
+
+  <p>Ngoài terminal thì cùng bộ lệnh đó bỏ dấu <span class="inline-code">/</span>: <span class="inline-code">piagent-mcp list</span>, <span class="inline-code">piagent-mcp doctor</span>. Thêm và xoá server chỉ có ở terminal. Chi tiết ở <a href="/mcp-servers">Quản lý server</a>.</p>
+</section>
+
+<section class="section">
+  <h2 id="ba-thu-trung-ten">Ba thứ trùng tên, không nối với nhau</h2>
+  <p>Đây là chỗ gây nhầm nhiều nhất. Không có dòng code nào map capability name sang MCP server id — khai <span class="inline-code">"github"</span> trong <span class="inline-code">mcpCapabilities</span> <strong>không</strong> bật server MCP tên <span class="inline-code">github</span>, và ngược lại.</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Thứ</th><th>Ở đâu</th><th>Là gì</th></tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><span class="inline-code">mcpCapabilities: ["github"]</span></td>
+          <td><span class="inline-code">.pi/piagent-profile.json</span></td>
+          <td>Nhãn capability cho tool registry</td>
+        </tr>
+        <tr>
+          <td><span class="inline-code">toolCapabilities</span></td>
+          <td><span class="inline-code">base-policy.json</span></td>
+          <td>Map một tool <strong>tên là</strong> <span class="inline-code">github</span> sang capability</td>
+        </tr>
+        <tr>
+          <td>server <span class="inline-code">github</span></td>
+          <td><span class="inline-code">~/.config/mcp/mcp.json</span></td>
+          <td>Server MCP thật, chạy qua Docker</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="bon-layer-config">Bốn layer config</h2>
+  <p>Cả bốn file đều được đọc. <span class="inline-code">--scope</span> của <span class="inline-code">piagent-mcp</span> chính là bốn tên này.</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Scope</th><th>File</th><th>Dùng khi nào</th></tr>
+      </thead>
+      <tbody>
+        <tr><td><span class="inline-code">global</span></td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>Mặc định. Dùng chung cho nhiều agent và nhiều project</td></tr>
+        <tr><td><span class="inline-code">pi-global</span></td><td><span class="inline-code">~/.pi/agent/mcp.json</span></td><td>Chỉ khi cần override riêng cho Pi</td></tr>
+        <tr><td><span class="inline-code">project</span></td><td><span class="inline-code">.mcp.json</span></td><td>Server đặc thù repo, commit được</td></tr>
+        <tr><td><span class="inline-code">pi-project</span></td><td><span class="inline-code">.pi/mcp.json</span></td><td>Override riêng Pi trong một repo</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div class="callout">
+    <strong>Hai layer cuối đi theo repo</strong>
+    <p>Clone một repo về là mang theo cả <span class="inline-code">.mcp.json</span> của nó. Vì vậy server ở hai scope đó phải qua <a href="/mcp-approval">approval gate</a> trước khi dùng được.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="preset">Preset seed sẵn</h2>
+  <p><span class="inline-code">piagent-setup</span> và <span class="inline-code">piagent-install</span> đều cài <span class="inline-code">pi-mcp-adapter</span> và seed preset <span class="inline-code">core</span> mặc định. Bỏ qua bằng <span class="inline-code">--no-mcp</span>.</p>
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Preset</th><th>Server</th><th>Mục đích</th></tr>
+      </thead>
+      <tbody>
+        <tr><td><span class="inline-code">minimal</span></td><td>—</td><td>Chỉ seed settings an toàn</td></tr>
+        <tr><td><span class="inline-code">docs</span></td><td>Context7</td><td>Docs mới của framework/library</td></tr>
+        <tr><td><span class="inline-code">browser</span></td><td>Chrome DevTools, Playwright</td><td>Inspect UI/runtime, browser automation</td></tr>
+        <tr><td><span class="inline-code">github</span></td><td>GitHub MCP</td><td>Issue/PR/repo/release workflow</td></tr>
+        <tr><td><span class="inline-code">design</span></td><td>Figma remote</td><td>Design-to-code qua Figma OAuth</td></tr>
+        <tr><td><span class="inline-code">design-local</span></td><td>Figma desktop</td><td>Dev Mode MCP chạy local</td></tr>
+        <tr><td><span class="inline-code">web</span></td><td>Context7, Chrome DevTools, Playwright</td><td>FE/web workflow</td></tr>
+        <tr><td><span class="inline-code">core</span></td><td>Context7, Chrome DevTools, GitHub</td><td>Baseline mặc định của team</td></tr>
+        <tr><td><span class="inline-code">popular</span></td><td>core + Playwright + Figma</td><td>Baseline nhiều team dev dùng</td></tr>
+        <tr><td><span class="inline-code">all</span></td><td>popular + Figma desktop</td><td>Đầy đủ</td></tr>
+      </tbody>
+    </table>
+  </div>
+
+  <p>Mọi server đều pin theo version hoặc digest. MCP server là code chạy trên máy operator với credential của operator, nên tag trôi nổi sẽ biến mỗi session thành một quyết định supply-chain không ai có mặt để duyệt.</p>
+
+  <div class="callout">
+    <strong>Ghi config không bằng dùng được</strong>
+    <p>Server connect lazy — không có gì được kiểm tra cho tới lần gọi đầu tiên. <a href="/mcp-auth">Trạng thái auth</a> cho biết server nào thật sự sẵn sàng.</p>
+  </div>
+</section>
+
+<section class="section">
+  <h2 id="token">Token efficiency</h2>
+  <p><span class="inline-code">pi-mcp-adapter</span> đưa mọi server qua một proxy tool duy nhất tên <span class="inline-code">mcp</span>, thay vì nạp toàn bộ tool schema vào context lúc start. Mặc định <span class="inline-code">directTools: false</span>, cộng với <span class="inline-code">outputGuard</span> và <span class="inline-code">idleTimeout</span>.</p>
+
+  <div class="callout">
+    <strong>Bẫy khi bật <span class="inline-code">toolRegistry: enforce</span></strong>
+    <p>Proxy tool tên <span class="inline-code">mcp</span> không nằm trong <span class="inline-code">alwaysAllowedTools</span> và không có trong <span class="inline-code">toolCapabilities</span>, nên <span class="inline-code">enforce</span> sẽ chặn <strong>toàn bộ</strong> MCP. Khai thêm <span class="inline-code">mcpCapabilities</span> không cứu được vì block xảy ra trước khi capability được đọc. Ngoại lệ duy nhất là permission profile <span class="inline-code">trusted-full-access</span>.</p>
+  </div>
+</section>

package/docs-site/content/permissions.html

@@ -0,0 +1,54 @@
+<section class="section">
+
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr>
+          <th>Mode</th>
+          <th>Dùng khi nào</th>
+          <th>Ranh giới</th>
+          <th>Command</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><span class="inline-code">read-only</span></td>
+          <td>Scout, audit, mapping, review không chỉnh source.</td>
+          <td>Cho read, grep, find, ls và piagent tools; chặn shell/write/unknown tools.</td>
+          <td><span class="inline-code">/read-only</span></td>
+        </tr>
+        <tr>
+          <td><span class="inline-code">workspace-write</span></td>
+          <td>Implementation bình thường trong repo.</td>
+          <td>Default guarded mode; giữ protected path, shell policy, capability và verify gate.</td>
+          <td><span class="inline-code">/workspace-write</span></td>
+        </tr>
+        <tr>
+          <td><span class="inline-code">trusted-full-access</span></td>
+          <td>Automation trên repo đã tin và task đã rõ.</td>
+          <td>Nới autonomy trong guard, nhưng vẫn giữ protected path, redaction, lock và confirmation.</td>
+          <td><span class="inline-code">/full-access</span></td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Xem permission</span><button class="clip-btn" data-clip="/permission-status">Lấy lệnh</button></header>
+      <pre><code>/permission-status</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Read-only session</span><button class="clip-btn" data-clip="/read-only">Lấy lệnh</button></header>
+      <pre><code>/read-only</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Workspace write</span><button class="clip-btn" data-clip="/workspace-write">Lấy lệnh</button></header>
+      <pre><code>/workspace-write</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Full-access + task</span><button class="clip-btn" data-clip="/full-access Run the trusted local verification suite.">Lấy lệnh</button></header>
+      <pre><code>/full-access Run the trusted local verification suite.</code></pre>
+    </article>
+  </div>
+</section>

package/docs-site/content/profiles.html

@@ -0,0 +1,68 @@
+<section class="section">
+
+  <div class="command-grid">
+    <article class="command-card">
+      <header><span>Xem status ngắn</span><button class="clip-btn" data-clip="/profile">Lấy lệnh</button></header>
+      <pre><code>/profile</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Liệt kê options</span><button class="clip-btn" data-clip="/profile list">Lấy lệnh</button></header>
+      <pre><code>/profile list</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Áp profile detect</span><button class="clip-btn" data-clip="/profile auto">Lấy lệnh</button></header>
+      <pre><code>/profile auto</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Setup bằng select</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>
+    </article>
+    <article class="command-card">
+      <header><span>Apply tech deterministic</span><button class="clip-btn" data-clip="/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma">Lấy lệnh</button></header>
+      <pre><code>/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Frontend</span><button class="clip-btn" data-clip="/profile web-frontend">Lấy lệnh</button></header>
+      <pre><code>/profile web-frontend
+/profile fe</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Backend/API</span><button class="clip-btn" data-clip="/profile backend-api">Lấy lệnh</button></header>
+      <pre><code>/profile backend-api</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Backend read-only, frontend write</span><button class="clip-btn" data-clip="/profile be-readonly-fe">Lấy lệnh</button></header>
+      <pre><code>/profile be-readonly-fe
+/profile be-fe</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Fullstack</span><button class="clip-btn" data-clip="/profile fullstack">Lấy lệnh</button></header>
+      <pre><code>/profile fullstack
+/profile full</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Docs-only</span><button class="clip-btn" data-clip="/profile docs">Lấy lệnh</button></header>
+      <pre><code>/profile docs</code></pre>
+    </article>
+  </div>
+
+  <div class="tag-list">
+    <span class="tag">generic</span>
+    <span class="tag">node-typescript</span>
+    <span class="tag">python</span>
+    <span class="tag">web-frontend</span>
+    <span class="tag">backend-api</span>
+    <span class="tag">fullstack</span>
+    <span class="tag">be-readonly-fe</span>
+    <span class="tag">data</span>
+    <span class="tag">devops</span>
+    <span class="tag">mobile</span>
+    <span class="tag">docs</span>
+  </div>
+
+  <div class="callout">
+    <strong>Tech stack theo role</strong>
+    <p>Frontend profile chọn FE + database optional; backend profile chọn BE + database optional; fullstack chọn đủ FE, BE và database. Sau đó platform tạo <span class="inline-code">.pi/tech-stack.json</span> và snapshot Context7 ngắn trong <span class="inline-code">.pi/tech-context/*</span>.</p>
+  </div>
+</section>

package/docs-site/content/quickstart.html

@@ -0,0 +1,144 @@
+<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 <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.2.1</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>
+              <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>Native Windows / WSL2</td>
+                <td>Chưa là target rollout team; WSL2 chỉ experimental.</td>
+              </tr>
+            </tbody>
+          </table>
+        </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
+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>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>
+        <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>
+
+    <article class="step">
+      <div>
+        <h3 id="onboard-context">Onboard context</h3>
+        <p>Chạy một lần ở repo mới để ghi context, verify matrix và protected areas vào <span class="inline-code">.pi/</span>.</p>
+        <div class="command-card">
+          <header><span>Onboard</span><button class="clip-btn" data-clip="/onboard-project">Lấy lệnh</button></header>
+          <pre><code>/onboard-project</code></pre>
+        </div>
+      </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>
+      </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="/workspace-write">Lấy lệnh</button></header>
+          <pre><code>/permission-status
+/workspace-write</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="chay-workflow">Chạy workflow</h3>
+        <p>Dùng command đúng mục tiêu để agent không phải diễn giải quá dài. Task nào nặng context thì dùng fresh session.</p>
+        <div class="command-card">
+          <header><span>Workflow</span><button class="clip-btn" data-clip="/task Implement the requested bounded change.">Lấy lệnh</button></header>
+          <pre><code>/task Implement the requested bounded change.
+/review
+/fresh-task Implement the requested bounded change.</code></pre>
+        </div>
+      </div>
+    </article>
+
+    <article class="step">
+      <div>
+        <h3 id="verify-truoc-khi-handoff">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. 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>
+      </div>
+    </article>
+
+    <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>
+
+  </div>
+</section>