npm - @piagent/platform - Versions diffs - 1.1.9 → 1.2.1 - Mend

@piagent/platform 1.1.9 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/CHANGELOG.md +175 -1
package/README.md +2 -2
package/docs/command-reference-vietnamese.md +19 -5
package/docs/distribution-standard.md +7 -7
package/docs/mcp-and-tools.md +154 -2
package/docs/model-options.md +10 -8
package/docs/operator-manual-vietnamese.md +25 -13
package/docs/publishing-for-teams.md +2 -0
package/docs/quickstart-vietnamese.md +2 -2
package/docs/release-install-policy.md +6 -6
package/docs/security-threat-model.md +4 -3
package/docs/team-onboarding.md +4 -4
package/docs/usage-observability.md +29 -0
package/docs/vercel-docs-site.md +34 -4
package/docs-site/architecture.html +152 -0
package/docs-site/assets/docs.css +1001 -0
package/docs-site/assets/docs.js +84 -0
package/docs-site/commands.html +203 -0
package/docs-site/content/architecture.html +29 -0
package/docs-site/content/commands.html +80 -0
package/docs-site/content/index.html +80 -0
package/docs-site/content/mcp-approval.html +133 -0
package/docs-site/content/mcp-auth.html +76 -0
package/docs-site/content/mcp-servers.html +111 -0
package/docs-site/content/mcp.html +120 -0
package/docs-site/content/permissions.html +54 -0
package/docs-site/content/profiles.html +68 -0
package/docs-site/content/quickstart.html +144 -0
package/docs-site/content/runtime.html +45 -0
package/docs-site/content/scope.html +71 -0
package/docs-site/content/security.html +51 -0
package/docs-site/content/team.html +23 -0
package/docs-site/content/workflows.html +47 -0
package/docs-site/index.html +131 -1534
package/docs-site/mcp-approval.html +256 -0
package/docs-site/mcp-auth.html +199 -0
package/docs-site/mcp-servers.html +234 -0
package/docs-site/mcp.html +243 -0
package/docs-site/permissions.html +177 -0
package/docs-site/profiles.html +191 -0
package/docs-site/quickstart.html +267 -0
package/docs-site/runtime.html +168 -0
package/docs-site/scope.html +194 -0
package/docs-site/security.html +174 -0
package/docs-site/team.html +142 -0
package/docs-site/workflows.html +170 -0
package/package.json +4 -2
package/packages/piagent-core/capabilities/capability-core.js +58 -5
package/packages/piagent-core/capabilities/capability-sources.js +73 -12
package/packages/piagent-core/extensions/document-intake.ts +5 -5
package/packages/piagent-core/extensions/piagent-guard.ts +432 -2
package/packages/piagent-core/extensions/policy-core.js +1586 -98
package/packages/piagent-core/mcp/mcp-approval-store.js +216 -0
package/packages/piagent-core/mcp/mcp-auth-readiness.js +225 -0
package/packages/piagent-core/mcp/mcp-command-actions.js +400 -0
package/packages/piagent-core/mcp/mcp-config-layers.js +466 -0
package/packages/piagent-core/mcp/mcp-import-kinds.js +240 -0
package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
package/packages/piagent-core/mcp/mcp-server-entry.js +293 -0
package/packages/piagent-core/mcp/mcp-session-view.js +236 -0
package/packages/piagent-core/mcp/mcp-tool-naming.js +90 -0
package/packages/piagent-core/package.json +7 -3
package/packages/piagent-core/prompts/model-options.md +8 -8
package/scripts/build-docs-site.mjs +421 -0
package/scripts/configure-model-scope.sh +21 -5
package/scripts/configure-subagents.sh +18 -5
package/scripts/init-project.sh +15 -8
package/scripts/install-global.sh +5 -5
package/scripts/mcp-manage.mjs +656 -0
package/scripts/pi-model-catalog.sh +11 -1
package/scripts/pi-session-stats.sh +27 -1
package/scripts/pi-usage-history.mjs +567 -0
package/scripts/piagent-cli.mjs +1 -1
package/scripts/preview-docs-site.mjs +88 -0
package/scripts/quality-benchmark.sh +37 -9
package/scripts/setup.sh +23 -15
package/scripts/team-doctor.sh +18 -2
package/scripts/uninstall-global.sh +10 -4
package/scripts/verify-local.sh +65 -19
package/scripts/verify-release-identity.mjs +37 -2
package/scripts/configure-mcp.sh +0 -349

package/docs-site/mcp-approval.html ADDED Viewed

@@ -0,0 +1,256 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Server đến từ repo phải được duyệt · Pi Agent Platform Docs</title>
+    <meta name="description" content="Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest." />
+    <meta name="theme-color" content="#050505" />
+    <link rel="canonical" href="https://piagent.io.vn/mcp-approval" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:title" content="Server đến từ repo phải được duyệt · Pi Agent Platform Docs" />
+    <meta property="og:description" content="Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest." />
+    <meta property="og:url" content="https://piagent.io.vn/mcp-approval" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/docs.css" />
+    <script src="/assets/docs.js" defer></script>
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="/" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
+        <span>Pi Agent Platform</span>
+      </a>
+      <div class="top-actions">
+        <span class="pill"><span class="pill-dot"></span>v1.2.1 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" />
+          </svg>
+          GitHub
+        </a>
+        <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
+        <a class="button" href="/commands">Commands</a>
+      </div>
+    </header>
+    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <div class="sidebar-search" aria-label="Tìm trong tài liệu">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+          <input type="search" placeholder="Tìm trang" data-filter />
+        </div>
+        <nav aria-label="Tài liệu">
+          <div class="nav-group">
+            <p class="nav-title">Get started</p>
+            <a class="nav-link" href="/">Overview</a>
+            <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/scope">Phạm vi platform</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Build</p>
+            <a class="nav-link" href="/profiles">Project profile</a>
+            <a class="nav-link" href="/permissions">Permission modes</a>
+            <a class="nav-link" href="/commands">Command catalog</a>
+            <a class="nav-link" href="/workflows">Workflows</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">MCP</p>
+            <a class="nav-link" href="/mcp">MCP overview</a>
+            <a class="nav-link" href="/mcp-servers">Quản lý server</a>
+            <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
+            <a class="nav-link current" href="/mcp-approval" aria-current="page">Approval gate</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Operate</p>
+            <a class="nav-link" href="/security">Security model</a>
+            <a class="nav-link" href="/architecture">Architecture</a>
+            <a class="nav-link" href="/runtime">Runtime tools</a>
+            <a class="nav-link" href="/team">Team usage</a>
+          </div>
+        </nav>
+      </aside>
+      <main>
+        <div class="content-shell" data-article>
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              <a href="/">Docs</a>
+              <span aria-hidden="true">/</span>
+              <span>MCP</span>
+              <span aria-hidden="true">/</span>
+              <span>Approval gate</span>
+            </nav>
+            <div class="page-head">
+              <h1>Server đến từ repo phải được duyệt</h1>
+              <p>Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest.</p>
+            </div>
+<section class="section">
+  <h2 id="van-de">Vấn đề</h2>
+  <p>Repo mang theo được <span class="inline-code">.mcp.json</span> và <span class="inline-code">.pi/mcp.json</span>. Clone một repo lạ rồi mở session <strong>không</strong> được phép cho tác giả repo đó một process trên máy mình, với credential của mình. Nên server ở hai scope này không dùng được cho tới khi có người trên máy này duyệt.</p>
+  <pre><code>/piagent-mcp get internal        # đọc trước
+/piagent-mcp approve internal    # hoặc reject, hoặc reset</code></pre>
+  <p>Trong terminal thì bỏ dấu <span class="inline-code">/</span>: <span class="inline-code">piagent-mcp get internal</span>. Cùng một quyết định, cùng một file.</p>
+  <p><span class="inline-code">approve</span> in ra định nghĩa trước khi ghi quyết định — duyệt mà không đọc chính là thứ gate này sinh ra để ngăn.</p>
+</section>
+<section class="section">
+  <h2 id="ba-tinh-chat">Ba tính chất</h2>
+  <div class="grid">
+    <div class="card">
+      <h3 id="ngoai-repo">Quyết định nằm ngoài repo</h3>
+      <p>Ghi vào <span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. Repo tự duyệt được cho chính nó thì gate coi như không tồn tại. Fork, đổi tên, checkout thứ hai — tất cả bắt đầu lại từ <span class="inline-code">pending</span>.</p>
+    </div>
+    <div class="card">
+      <h3 id="pin-digest">Pin theo digest</h3>
+      <p>Duyệt là đồng ý với <em>thứ server đó chạy</em>. Đổi command, URL hay args là một câu hỏi mới, state về <span class="inline-code">approval-changed</span>. Cùng cách tách consent với build mà capability lock đang dùng.</p>
+    </div>
+    <div class="card">
+      <h3 id="enforce-tool-call">Enforce ở tool call</h3>
+      <p>Guard đọc cả proxy (<span class="inline-code">mcp</span> với <span class="inline-code">input.server</span>) lẫn direct tool. Gate chỉ đọc proxy sẽ bị đi vòng bằng cách bật <span class="inline-code">directTools</span>.</p>
+    </div>
+  </div>
+</section>
+<section class="section">
+  <h2 id="gioi-han">Giới hạn</h2>
+  <div class="callout">
+    <strong>Không chặn được connection</strong>
+    <p>Adapter sở hữu kết nối; extension không ngăn được việc một kết nối được mở. Cái bị chặn là <strong>mọi tool call</strong>, không phải bản thân kết nối. Phần rủi ro còn lại là chính kết nối đó, và việc server phía kia ghi log rằng có người kết nối tới.</p>
+  </div>
+  <p>Server ở <span class="inline-code">global</span> và <span class="inline-code">pi-global</span> không qua gate. Hai layer đó nằm ngoài mọi repo — không repo nào đặt được server vào đó — và bắt người dùng duyệt config của chính mình trên từng máy là vô nghĩa.</p>
+</section>
+<section class="section">
+  <h2 id="imports">Server đến qua <span class="inline-code">imports</span></h2>
+  <p>Config MCP nhận thêm key <span class="inline-code">imports</span>, kéo định nghĩa server từ config của công cụ khác. Server vào session theo đường này không nằm trong bốn scope nào, nên nó là đường vòng thứ hai quanh gate — và không cần bật <span class="inline-code">directTools</span>.</p>
+  <p>Trong sáu kind, chỉ <span class="inline-code">vscode</span> trỏ vào đường dẫn <strong>trong project</strong> (<span class="inline-code">.vscode/mcp.json</span>). Clone repo là mang theo file đó, nên server của nó phải duyệt như mọi server repo khai báo thẳng.</p>
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Tình huống</th><th>Xử lý</th></tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Layer bất kỳ import kind repo-relative</td>
+          <td>Server phải duyệt, kể cả khi <span class="inline-code">global</span> khai báo — nội dung đọc lại vẫn nằm trong repo.</td>
+        </tr>
+        <tr>
+          <td>Repo scope import kind bất kỳ</td>
+          <td>Server phải duyệt. Repo đang chọn hộ máy này chạy server nào.</td>
+        </tr>
+        <tr>
+          <td>Repo scope import kind không đọc được nội dung (<span class="inline-code">codex</span>, TOML)</td>
+          <td>Chặn mọi tool call, khi file đó có thật trên máy. Từ chối ở dòng khai báo: liệt kê được server của năm kind kia không nói gì về kind thứ sáu. Khai một kind máy này không cài thì là config cần dọn, không phải session cần dừng.</td>
+        </tr>
+        <tr>
+          <td><span class="inline-code">remove</span> / <span class="inline-code">enable</span> / <span class="inline-code">disable</span> trên server đến qua <span class="inline-code">imports</span></td>
+          <td>Từ chối, kèm tên file thật cần sửa. File được định vị là config của công cụ kia; ghi ngược bằng writer của platform sẽ viết lại file Cursor/VS Code của người dùng theo format chính công cụ đó không dùng.</td>
+        </tr>
+        <tr>
+          <td><span class="inline-code">directTools</span> + <span class="inline-code">toolPrefix: "none"</span> trong config repo mang theo</td>
+          <td>Chặn mọi tool call, không riêng lời gọi MCP. Không prefix thì tên tool không còn dấu vết server, không truy được để đối chiếu quyết định — mà chặn riêng proxy <span class="inline-code">mcp</span> thì đúng những cái tên trần cần chặn lại đi thẳng qua.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <p><span class="inline-code">piagent-mcp doctor</span> nêu tên file có <span class="inline-code">imports</span> và các kind của nó, nêu layer không parse được, và nêu cả import target <em>có thật nhưng không đọc được</em> — cả ba trạng thái trước đây đều đọc ra rỗng, không phân biệt được với &ldquo;không khai server nào&rdquo;.</p>
+  <p>Với hai trạng thái chặn-toàn-bộ ở trên, <span class="inline-code">doctor</span> và <span class="inline-code">list</span> in ra lý do và exit 1 — kể cả <span class="inline-code">list --json</span>, vốn trả <span class="inline-code">servers: []</span> với exit 0 đúng lúc không gì chạy được. Exit code trả lời &ldquo;MCP ở đây có chạy được không&rdquo;, không phải &ldquo;có in ra dòng nào không&rdquo;. Cả ba surface — guard, <span class="inline-code">/piagent-mcp</span>, CLI — đọc một state chung, vì hai bên lệch nhau chính là cách một session bị chặn biến thành một session hỏng không rõ lý do.</p>
+  <p>Gate được cache theo project và tính lại khi signature trên các file phía sau nó đổi. Danh sách file đó lấy từ chính đường đi mà các reader dùng, kể cả file đang không tồn tại — <span class="inline-code">imports: ["codex"]</span> thành chặn đúng lúc file codex xuất hiện, và <span class="inline-code">directTools</span> thêm vào config global cá nhân là thứ guard đã load phải thấy ngay. Viết tay danh sách đó là cách nó lệch.</p>
+  <p>Adapter merge <span class="inline-code">settings</span> của cả bốn layer thành một block cho cả session. Nên <span class="inline-code">directTools</span> đặt ở file này và <span class="inline-code">toolPrefix: "none"</span> đặt ở file kia vẫn ra đúng tổ hợp làm gate mất chỗ bám, trong khi đọc riêng từng file thì không file nào có vấn đề. Settings được đọc sau merge, và báo cả hai file.</p>
+  <p>Cột <span class="inline-code">SCOPE</span> là layer khai báo <span class="inline-code">imports</span>, không phải nơi server được định nghĩa. Server import qua config <span class="inline-code">global</span> vẫn cần duyệt, vì file đọc lại nằm trong clone.</p>
+</section>
+<section class="section">
+  <h2 id="thiet-ke">Bốn quyết định thiết kế</h2>
+  <div class="table-wrap">
+    <table>
+      <thead>
+        <tr><th>Quyết định</th><th>Vì sao</th></tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Chỉ gate server đến từ repo</td>
+          <td>Chỉ <span class="inline-code">.mcp.json</span> và <span class="inline-code">.pi/mcp.json</span> đi theo clone. Server người dùng tự đặt trên máy mình không cần ai duyệt.</td>
+        </tr>
+        <tr>
+          <td>Quyết định lưu ngoài repo</td>
+          <td><span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. Nếu lưu trong repo thì repo tự duyệt cho chính nó — gate mất nghĩa ngay từ đầu.</td>
+        </tr>
+        <tr>
+          <td>Pin theo digest của định nghĩa</td>
+          <td>Duyệt là duyệt <em>đúng</em> command và URL đó. Đổi command, đổi args, đổi URL thì server quay về <span class="inline-code">pending</span> chứ không kế thừa quyết định cũ.</td>
+        </tr>
+        <tr>
+          <td>Preview in ra bản đã merge, digest tính trên mảnh của repo</td>
+          <td>Adapter merge server trùng tên theo từng key qua các layer, nên repo khai mỗi <span class="inline-code">{"args": [...]}</span> vẫn lấy <span class="inline-code">command</span> từ layer dưới. Preview phải là thứ sẽ chạy thật. Digest thì giữ trên phần repo kiểm soát — băm cả bản merge sẽ đẩy server về <span class="inline-code">pending</span> mỗi lần người dùng sửa config global của chính mình.</td>
+        </tr>
+        <tr>
+          <td>Chặn ở <span class="inline-code">tool_call</span></td>
+          <td>Cả dạng proxy <span class="inline-code">mcp</span> lẫn direct tool, để không có đường vòng. Direct tool được truy theo tên server đang cấu hình, vì prefix của nó chính là tên server.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <p>Điểm chặn lý tưởng là trước khi connect, nhưng chặn được ở đó thì phải sở hữu connection. Platform chạy trong Pi và không sở hữu nó, nên nó chọn điểm chặn xa nhất mà nó thật sự kiểm soát được — rồi nói rõ phần còn thừa thay vì để người đọc tự suy ra.</p>
+</section>
+<section class="section">
+  <h2 id="migration">Migration</h2>
+  <div class="callout">
+    <strong>Project đã có server từ trước</strong>
+    <p>Project nào đã có server trong <span class="inline-code">.mcp.json</span> hoặc <span class="inline-code">.pi/mcp.json</span> sẽ chuyển sang <span class="inline-code">pending-approval</span> sau khi update. Chạy <span class="inline-code">/piagent-mcp approve &lt;name&gt;</span> một lần cho mỗi project. Template ship rỗng nên đa số project không bị ảnh hưởng; notice đầu session và <span class="inline-code">doctor</span> đều nêu tên server cần duyệt.</p>
+  </div>
+</section>
+            <nav class="pager" aria-label="Trang kế tiếp">
+              <a class="pager-prev" href="/mcp-auth">
+                <span class="pager-label">Trước</span>
+                <span class="pager-title">Auth và readiness</span>
+              </a>
+              <a class="pager-next" href="/security">
+                <span class="pager-label">Tiếp</span>
+                <span class="pager-title">Security model</span>
+              </a>
+            </nav>
+            <footer class="footer">
+              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
+              <div class="footer-links" aria-label="External links">
+                <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
+                <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
+              </div>
+            </footer>
+        </div>
+      </main>
+      <aside class="toc" aria-label="Mục lục trang">
+        <p class="toc-title">Trên trang này</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+  </body>
+</html>

package/docs-site/mcp-auth.html ADDED Viewed

@@ -0,0 +1,199 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Đăng nhập và trạng thái sẵn sàng · Pi Agent Platform Docs</title>
+    <meta name="description" content="Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được." />
+    <meta name="theme-color" content="#050505" />
+    <link rel="canonical" href="https://piagent.io.vn/mcp-auth" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:title" content="Đăng nhập và trạng thái sẵn sàng · Pi Agent Platform Docs" />
+    <meta property="og:description" content="Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được." />
+    <meta property="og:url" content="https://piagent.io.vn/mcp-auth" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/docs.css" />
+    <script src="/assets/docs.js" defer></script>
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="/" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
+        <span>Pi Agent Platform</span>
+      </a>
+      <div class="top-actions">
+        <span class="pill"><span class="pill-dot"></span>v1.2.1 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" />
+          </svg>
+          GitHub
+        </a>
+        <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
+        <a class="button" href="/commands">Commands</a>
+      </div>
+    </header>
+    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <div class="sidebar-search" aria-label="Tìm trong tài liệu">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+          <input type="search" placeholder="Tìm trang" data-filter />
+        </div>
+        <nav aria-label="Tài liệu">
+          <div class="nav-group">
+            <p class="nav-title">Get started</p>
+            <a class="nav-link" href="/">Overview</a>
+            <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/scope">Phạm vi platform</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Build</p>
+            <a class="nav-link" href="/profiles">Project profile</a>
+            <a class="nav-link" href="/permissions">Permission modes</a>
+            <a class="nav-link" href="/commands">Command catalog</a>
+            <a class="nav-link" href="/workflows">Workflows</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">MCP</p>
+            <a class="nav-link" href="/mcp">MCP overview</a>
+            <a class="nav-link" href="/mcp-servers">Quản lý server</a>
+            <a class="nav-link current" href="/mcp-auth" aria-current="page">Auth và readiness</a>
+            <a class="nav-link" href="/mcp-approval">Approval gate</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Operate</p>
+            <a class="nav-link" href="/security">Security model</a>
+            <a class="nav-link" href="/architecture">Architecture</a>
+            <a class="nav-link" href="/runtime">Runtime tools</a>
+            <a class="nav-link" href="/team">Team usage</a>
+          </div>
+        </nav>
+      </aside>
+      <main>
+        <div class="content-shell" data-article>
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              <a href="/">Docs</a>
+              <span aria-hidden="true">/</span>
+              <span>MCP</span>
+              <span aria-hidden="true">/</span>
+              <span>Auth và readiness</span>
+            </nav>
+            <div class="page-head">
+              <h1>Đăng nhập và trạng thái sẵn sàng</h1>
+              <p>Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được.</p>
+            </div>
+<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>
+            <nav class="pager" aria-label="Trang kế tiếp">
+              <a class="pager-prev" href="/mcp-servers">
+                <span class="pager-label">Trước</span>
+                <span class="pager-title">Quản lý server</span>
+              </a>
+              <a class="pager-next" href="/mcp-approval">
+                <span class="pager-label">Tiếp</span>
+                <span class="pager-title">Approval gate</span>
+              </a>
+            </nav>
+            <footer class="footer">
+              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
+              <div class="footer-links" aria-label="External links">
+                <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
+                <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
+              </div>
+            </footer>
+        </div>
+      </main>
+      <aside class="toc" aria-label="Mục lục trang">
+        <p class="toc-title">Trên trang này</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+  </body>
+</html>