@piagent/platform 1.1.9 → 1.2.0

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 (70) hide show
  1. package/CHANGELOG.md +43 -1
  2. package/README.md +2 -2
  3. package/docs/command-reference-vietnamese.md +13 -4
  4. package/docs/distribution-standard.md +7 -7
  5. package/docs/mcp-and-tools.md +108 -2
  6. package/docs/model-options.md +10 -8
  7. package/docs/operator-manual-vietnamese.md +12 -12
  8. package/docs/publishing-for-teams.md +1 -0
  9. package/docs/quickstart-vietnamese.md +2 -2
  10. package/docs/release-install-policy.md +6 -6
  11. package/docs/security-threat-model.md +1 -1
  12. package/docs/team-onboarding.md +4 -4
  13. package/docs/vercel-docs-site.md +34 -4
  14. package/docs-site/architecture.html +152 -0
  15. package/docs-site/assets/docs.css +1001 -0
  16. package/docs-site/assets/docs.js +84 -0
  17. package/docs-site/commands.html +203 -0
  18. package/docs-site/content/architecture.html +29 -0
  19. package/docs-site/content/commands.html +80 -0
  20. package/docs-site/content/index.html +80 -0
  21. package/docs-site/content/mcp-approval.html +81 -0
  22. package/docs-site/content/mcp-auth.html +76 -0
  23. package/docs-site/content/mcp-servers.html +111 -0
  24. package/docs-site/content/mcp.html +120 -0
  25. package/docs-site/content/permissions.html +54 -0
  26. package/docs-site/content/profiles.html +68 -0
  27. package/docs-site/content/quickstart.html +144 -0
  28. package/docs-site/content/runtime.html +45 -0
  29. package/docs-site/content/scope.html +71 -0
  30. package/docs-site/content/security.html +51 -0
  31. package/docs-site/content/team.html +23 -0
  32. package/docs-site/content/workflows.html +47 -0
  33. package/docs-site/index.html +131 -1534
  34. package/docs-site/mcp-approval.html +204 -0
  35. package/docs-site/mcp-auth.html +199 -0
  36. package/docs-site/mcp-servers.html +234 -0
  37. package/docs-site/mcp.html +243 -0
  38. package/docs-site/permissions.html +177 -0
  39. package/docs-site/profiles.html +191 -0
  40. package/docs-site/quickstart.html +267 -0
  41. package/docs-site/runtime.html +168 -0
  42. package/docs-site/scope.html +194 -0
  43. package/docs-site/security.html +174 -0
  44. package/docs-site/team.html +142 -0
  45. package/docs-site/workflows.html +170 -0
  46. package/package.json +4 -2
  47. package/packages/piagent-core/capabilities/capability-core.js +17 -1
  48. package/packages/piagent-core/extensions/document-intake.ts +5 -5
  49. package/packages/piagent-core/extensions/piagent-guard.ts +316 -0
  50. package/packages/piagent-core/mcp/mcp-approval-store.js +175 -0
  51. package/packages/piagent-core/mcp/mcp-auth-readiness.js +197 -0
  52. package/packages/piagent-core/mcp/mcp-command-actions.js +291 -0
  53. package/packages/piagent-core/mcp/mcp-config-layers.js +133 -0
  54. package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
  55. package/packages/piagent-core/mcp/mcp-server-entry.js +242 -0
  56. package/packages/piagent-core/mcp/mcp-session-view.js +185 -0
  57. package/packages/piagent-core/package.json +7 -3
  58. package/packages/piagent-core/prompts/model-options.md +8 -8
  59. package/scripts/build-docs-site.mjs +421 -0
  60. package/scripts/configure-model-scope.sh +2 -2
  61. package/scripts/configure-subagents.sh +1 -1
  62. package/scripts/install-global.sh +5 -5
  63. package/scripts/mcp-manage.mjs +567 -0
  64. package/scripts/piagent-cli.mjs +1 -1
  65. package/scripts/preview-docs-site.mjs +88 -0
  66. package/scripts/setup.sh +2 -2
  67. package/scripts/team-doctor.sh +18 -2
  68. package/scripts/verify-local.sh +46 -19
  69. package/scripts/verify-release-identity.mjs +8 -2
  70. package/scripts/configure-mcp.sh +0 -349
package/docs-site/assets/docs.js ADDED
@@ -0,0 +1,84 @@
1
+ // Behaviour shared by every docs page. Loaded with `defer`, so the DOM is parsed
2
+ // before any of this runs and no page needs an inline script of its own.
3
+
4
+ const sidebar = document.querySelector("[data-sidebar]");
5
+ const menuButton = document.querySelector("[data-menu]");
6
+ const filterInput = document.querySelector("[data-filter]");
7
+ const navLinks = Array.from(document.querySelectorAll(".nav-link"));
8
+
9
+ menuButton?.addEventListener("click", () => {
10
+ sidebar?.classList.toggle("open");
11
+ });
12
+
13
+ navLinks.forEach((link) => {
14
+ link.addEventListener("click", () => sidebar?.classList.remove("open"));
15
+ });
16
+
17
+ // The filter hides whole groups once none of their links match, so a search that
18
+ // finds nothing in a group does not leave its heading floating over a gap.
19
+ filterInput?.addEventListener("input", (event) => {
20
+ const value = event.target.value.trim().toLowerCase();
21
+ navLinks.forEach((link) => {
22
+ const text = link.textContent.toLowerCase();
23
+ link.style.display = !value || text.includes(value) ? "flex" : "none";
24
+ });
25
+ document.querySelectorAll(".nav-group").forEach((group) => {
26
+ const visible = Array.from(group.querySelectorAll(".nav-link")).some((link) => link.style.display !== "none");
27
+ group.style.display = visible ? "" : "none";
28
+ });
29
+ });
30
+
31
+ // Table of contents, built from the headings the page actually has. Generating it
32
+ // here rather than writing it into each page means a heading can never be renamed
33
+ // in the prose and left stale in the sidebar.
34
+ const tocHost = document.querySelector("[data-toc]");
35
+ const article = document.querySelector("[data-article]");
36
+
37
+ if (tocHost && article) {
38
+ const headings = Array.from(article.querySelectorAll("h2[id], h3[id]"));
39
+ if (headings.length < 2) {
40
+ tocHost.remove();
41
+ document.querySelector(".layout")?.classList.remove("with-toc");
42
+ } else {
43
+ for (const heading of headings) {
44
+ const link = document.createElement("a");
45
+ link.href = `#${heading.id}`;
46
+ link.textContent = heading.textContent.trim();
47
+ if (heading.tagName === "H3") link.classList.add("toc-h3");
48
+ tocHost.append(link);
49
+ }
50
+
51
+ const tocLinks = Array.from(tocHost.querySelectorAll("a"));
52
+ const observer = new IntersectionObserver(
53
+ (entries) => {
54
+ const visible = entries
55
+ .filter((entry) => entry.isIntersecting)
56
+ .sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0];
57
+ if (!visible) return;
58
+ for (const link of tocLinks) {
59
+ link.classList.toggle("active", link.getAttribute("href") === `#${visible.target.id}`);
60
+ }
61
+ },
62
+ { rootMargin: "-12% 0px -70% 0px", threshold: [0.1, 0.5, 1] }
63
+ );
64
+ for (const heading of headings) observer.observe(heading);
65
+ }
66
+ }
67
+
68
+ // Copy buttons carry the command in an attribute so the visible text can stay
69
+ // formatted; the label says what happened and goes back on its own.
70
+ document.querySelectorAll("[data-clip]").forEach((button) => {
71
+ button.addEventListener("click", async () => {
72
+ const text = button.getAttribute("data-clip") || "";
73
+ const original = button.textContent;
74
+ try {
75
+ await navigator.clipboard.writeText(text);
76
+ button.textContent = "Đã lấy";
77
+ } catch {
78
+ button.textContent = "Chọn lệnh";
79
+ }
80
+ setTimeout(() => {
81
+ button.textContent = original;
82
+ }, 1200);
83
+ });
84
+ });
package/docs-site/commands.html ADDED
@@ -0,0 +1,203 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Command ngắn, rõ, ít token burn · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Ưu tiên dùng slash command vì mỗi command đã gói sẵn policy và flow. Thành viên không cần nhớ lại quy trình trong prompt." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/commands" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Command ngắn, rõ, ít token burn · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Ưu tiên dùng slash command vì mỗi command đã gói sẵn policy và flow. Thành viên không cần nhớ lại quy trình trong prompt." />
13
+ <meta property="og:url" content="https://piagent.io.vn/commands" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ 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"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <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" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link" href="/scope">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link current" href="/commands" aria-current="page">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link" href="/mcp">MCP overview</a>
68
+ <a class="nav-link" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link" href="/security">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link" href="/runtime">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>Build</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Command catalog</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Command ngắn, rõ, ít token burn</h1>
93
+ <p>Ưu tiên dùng slash command vì mỗi command đã gói sẵn policy và flow. Thành viên không cần nhớ lại quy trình trong prompt.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="grid cols-2">
98
+ <article class="card">
99
+ <h3 id="session-basics">Session basics</h3>
100
+ <div class="tag-list">
101
+ <span class="tag">/login</span>
102
+ <span class="tag">/model</span>
103
+ <span class="tag">/piagent-commands</span>
104
+ <span class="tag">/piagent-status</span>
105
+ <span class="tag">/piagent-orchestration</span>
106
+ <span class="tag">/piagent-usage</span>
107
+ <span class="tag">/task-preflight</span>
108
+ </div>
109
+ <p>Dùng để setup session, chọn model, xem profile/usage/orchestration và quyết định có cần fresh session trước task lớn không.</p>
110
+ </article>
111
+ <article class="card">
112
+ <h3 id="project-profile">Project profile</h3>
113
+ <div class="tag-list">
114
+ <span class="tag">/profile</span>
115
+ <span class="tag">/profile list</span>
116
+ <span class="tag">/profile auto</span>
117
+ <span class="tag">/profile setup</span>
118
+ <span class="tag">/profile tech</span>
119
+ <span class="tag">/profile tech setup</span>
120
+ <span class="tag">/profile fullstack</span>
121
+ <span class="tag">/profile be-fe</span>
122
+ </div>
123
+ <p>Áp profile trực tiếp hoặc mở select option để chọn profile/tech stack. Output ngắn, không yêu cầu model giải thích dài.</p>
124
+ </article>
125
+ <article class="card">
126
+ <h3 id="implementation-workflow">Implementation workflow</h3>
127
+ <div class="tag-list">
128
+ <span class="tag">/task</span>
129
+ <span class="tag">/plan</span>
130
+ <span class="tag">/review</span>
131
+ <span class="tag">/scout</span>
132
+ <span class="tag">/discuss</span>
133
+ </div>
134
+ <p>Gói sẵn read context, task contract, implementation, verify evidence và final handoff.</p>
135
+ </article>
136
+ <article class="card">
137
+ <h3 id="git-handoff">Git handoff</h3>
138
+ <div class="tag-list">
139
+ <span class="tag">/commit</span>
140
+ <span class="tag">/pr</span>
141
+ <span class="tag">git status</span>
142
+ <span class="tag">git diff</span>
143
+ </div>
144
+ <p>Không cần namespace <span class="inline-code">/git</span>. Commit/PR đi qua shell guard; push và stage rộng như <span class="inline-code">git add -A</span> cần xác nhận.</p>
145
+ </article>
146
+ <article class="card">
147
+ <h3 id="fresh-sessions">Fresh sessions</h3>
148
+ <div class="tag-list">
149
+ <span class="tag">/fresh-task</span>
150
+ <span class="tag">/fresh-scout</span>
151
+ <span class="tag">/fresh-be-to-fe</span>
152
+ </div>
153
+ <p>Dùng khi context đã nặng hoặc cần một session sạch cho workflow mới.</p>
154
+ </article>
155
+ <article class="card">
156
+ <h3 id="mcp">MCP</h3>
157
+ <div class="tag-list">
158
+ <span class="tag">/mcp</span>
159
+ <span class="tag">piagent-mcp</span>
160
+ </div>
161
+ <p>Kiểm tra và cấu hình tool servers theo preset core, popular hoặc design.</p>
162
+ </article>
163
+ <article class="card">
164
+ <h3 id="subagents">Subagents</h3>
165
+ <div class="tag-list">
166
+ <span class="tag">/subagents-doctor</span>
167
+ <span class="tag">/subagents-models</span>
168
+ <span class="tag">/subagents-fleet</span>
169
+ <span class="tag">/subagent-cost</span>
170
+ </div>
171
+ <p>Kiểm tra runtime, model routing, background runs và cost. Daily flow vẫn solo-first; subagents dùng cho scout/planning/review độc lập.</p>
172
+ </article>
173
+ </div>
174
+ </section>
175
+ <nav class="pager" aria-label="Trang kế tiếp">
176
+ <a class="pager-prev" href="/permissions">
177
+ <span class="pager-label">Trước</span>
178
+ <span class="pager-title">Permission modes</span>
179
+ </a>
180
+ <a class="pager-next" href="/workflows">
181
+ <span class="pager-label">Tiếp</span>
182
+ <span class="pager-title">Workflows</span>
183
+ </a>
184
+ </nav>
185
+
186
+ <footer class="footer">
187
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
188
+ <div class="footer-links" aria-label="External links">
189
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
190
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
191
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
192
+ </div>
193
+ </footer>
194
+ </div>
195
+ </main>
196
+
197
+ <aside class="toc" aria-label="Mục lục trang">
198
+ <p class="toc-title">Trên trang này</p>
199
+ <nav data-toc></nav>
200
+ </aside>
201
+ </div>
202
+ </body>
203
+ </html>
package/docs-site/content/architecture.html ADDED
@@ -0,0 +1,29 @@
1
+ <section class="section">
2
+
3
+ <div class="grid cols-3">
4
+ <article class="card">
5
+ <h3 id="core-package">Core package</h3>
6
+ <p><span class="inline-code">packages/piagent-core</span> chứa extension guard, prompts, skills và subagent roles.</p>
7
+ </article>
8
+ <article class="card">
9
+ <h3 id="adapters">Adapters</h3>
10
+ <p><span class="inline-code">adapters/</span> chứa profile dùng lại: frontend, backend, fullstack, data, devops, docs.</p>
11
+ </article>
12
+ <article class="card">
13
+ <h3 id="capability-packs">Capability packs</h3>
14
+ <p><span class="inline-code">packs/</span> gom policy, lifecycle, recipes và eval scenarios theo manifest có lock.</p>
15
+ </article>
16
+ <article class="card">
17
+ <h3 id="policies">Policies</h3>
18
+ <p>Base policy định nghĩa protected paths, command rules, permission modes và human-action gates.</p>
19
+ </article>
20
+ <article class="card">
21
+ <h3 id="scripts">Scripts</h3>
22
+ <p>Setup, doctor, model scope, MCP, subagents, benchmark và trusted-run wrapper đều có CLI riêng.</p>
23
+ </article>
24
+ <article class="card">
25
+ <h3 id="docs">Docs</h3>
26
+ <p><span class="inline-code">docs/</span> giữ manual dài. <span class="inline-code">docs-site/</span> là trang HTML gọn cho team.</p>
27
+ </article>
28
+ </div>
29
+ </section>
package/docs-site/content/commands.html ADDED
@@ -0,0 +1,80 @@
1
+ <section class="section">
2
+
3
+ <div class="grid cols-2">
4
+ <article class="card">
5
+ <h3 id="session-basics">Session basics</h3>
6
+ <div class="tag-list">
7
+ <span class="tag">/login</span>
8
+ <span class="tag">/model</span>
9
+ <span class="tag">/piagent-commands</span>
10
+ <span class="tag">/piagent-status</span>
11
+ <span class="tag">/piagent-orchestration</span>
12
+ <span class="tag">/piagent-usage</span>
13
+ <span class="tag">/task-preflight</span>
14
+ </div>
15
+ <p>Dùng để setup session, chọn model, xem profile/usage/orchestration và quyết định có cần fresh session trước task lớn không.</p>
16
+ </article>
17
+ <article class="card">
18
+ <h3 id="project-profile">Project profile</h3>
19
+ <div class="tag-list">
20
+ <span class="tag">/profile</span>
21
+ <span class="tag">/profile list</span>
22
+ <span class="tag">/profile auto</span>
23
+ <span class="tag">/profile setup</span>
24
+ <span class="tag">/profile tech</span>
25
+ <span class="tag">/profile tech setup</span>
26
+ <span class="tag">/profile fullstack</span>
27
+ <span class="tag">/profile be-fe</span>
28
+ </div>
29
+ <p>Áp profile trực tiếp hoặc mở select option để chọn profile/tech stack. Output ngắn, không yêu cầu model giải thích dài.</p>
30
+ </article>
31
+ <article class="card">
32
+ <h3 id="implementation-workflow">Implementation workflow</h3>
33
+ <div class="tag-list">
34
+ <span class="tag">/task</span>
35
+ <span class="tag">/plan</span>
36
+ <span class="tag">/review</span>
37
+ <span class="tag">/scout</span>
38
+ <span class="tag">/discuss</span>
39
+ </div>
40
+ <p>Gói sẵn read context, task contract, implementation, verify evidence và final handoff.</p>
41
+ </article>
42
+ <article class="card">
43
+ <h3 id="git-handoff">Git handoff</h3>
44
+ <div class="tag-list">
45
+ <span class="tag">/commit</span>
46
+ <span class="tag">/pr</span>
47
+ <span class="tag">git status</span>
48
+ <span class="tag">git diff</span>
49
+ </div>
50
+ <p>Không cần namespace <span class="inline-code">/git</span>. Commit/PR đi qua shell guard; push và stage rộng như <span class="inline-code">git add -A</span> cần xác nhận.</p>
51
+ </article>
52
+ <article class="card">
53
+ <h3 id="fresh-sessions">Fresh sessions</h3>
54
+ <div class="tag-list">
55
+ <span class="tag">/fresh-task</span>
56
+ <span class="tag">/fresh-scout</span>
57
+ <span class="tag">/fresh-be-to-fe</span>
58
+ </div>
59
+ <p>Dùng khi context đã nặng hoặc cần một session sạch cho workflow mới.</p>
60
+ </article>
61
+ <article class="card">
62
+ <h3 id="mcp">MCP</h3>
63
+ <div class="tag-list">
64
+ <span class="tag">/mcp</span>
65
+ <span class="tag">piagent-mcp</span>
66
+ </div>
67
+ <p>Kiểm tra và cấu hình tool servers theo preset core, popular hoặc design.</p>
68
+ </article>
69
+ <article class="card">
70
+ <h3 id="subagents">Subagents</h3>
71
+ <div class="tag-list">
72
+ <span class="tag">/subagents-doctor</span>
73
+ <span class="tag">/subagents-models</span>
74
+ <span class="tag">/subagents-fleet</span>
75
+ <span class="tag">/subagent-cost</span>
76
+ </div>
77
+ <p>Kiểm tra runtime, model routing, background runs và cost. Daily flow vẫn solo-first; subagents dùng cho scout/planning/review độc lập.</p>
78
+ </article>
79
+ </div>
80
+ </section>
package/docs-site/content/index.html ADDED
@@ -0,0 +1,80 @@
1
+ <section class="hero">
2
+ <p class="eyebrow">Team operating docs</p>
3
+ <h1>Pi runtime được đóng gói như một nền tảng dùng lại cho nhiều dự án.</h1>
4
+ <p>
5
+ Tài liệu này gom phần cài đặt, profile, quyền chạy, MCP, bảo mật và workflow vào một nơi duy nhất. Mục tiêu là thành viên mới chỉ cần mở trang này, chọn đúng command, chạy đúng chế độ và biết ranh giới an toàn.
6
+ </p>
7
+ <div class="owner-strip" aria-label="Thông tin dự án">
8
+ <span class="owner-label">Project links</span>
9
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">Docs · piagent.io.vn</a>
10
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub · Vt-mmm/piagent</a>
11
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook · Vĩnh Tâm</a>
12
+ </div>
13
+ <div class="hero-actions">
14
+ <a class="button primary" href="/quickstart">Bắt đầu</a>
15
+ <a class="button" href="/commands">Xem command</a>
16
+ <a class="button" href="/mcp">MCP</a>
17
+ </div>
18
+ </section>
19
+
20
+ <section class="section">
21
+ <h2 id="cai-dat">Cài trong hai lệnh</h2>
22
+ <p>Node.js <span class="inline-code">&gt;=22.19.0</span>. Chạy từ đúng project muốn set up.</p>
23
+ <pre><code>npm install -g @piagent/platform
24
+ piagent-setup</code></pre>
25
+ <p><span class="inline-code">piagent-setup</span> cài đúng Pi Coding Agent host mà release này pin, cài Pi package, khởi tạo thư mục hiện tại, rồi chạy doctor. Nó cũng cài MCP baseline và subagents — bỏ qua bằng <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span> hoặc <span class="inline-code">--global-only</span>. Chi tiết ở <a href="/quickstart">Quickstart</a>.</p>
26
+ </section>
27
+
28
+ <section class="section">
29
+ <h2 id="bat-dau-tu-dau">Bắt đầu từ đâu</h2>
30
+ <div class="card-grid">
31
+ <a class="doc-card" href="/quickstart">
32
+ <span class="card-kicker">Get started</span>
33
+ <h3>Quickstart</h3>
34
+ <p>Cài, mở repo, onboard context, chọn profile và permission, chạy task đầu tiên, verify trước khi handoff.</p>
35
+ </a>
36
+ <a class="doc-card" href="/scope">
37
+ <span class="card-kicker">Get started</span>
38
+ <h3>Phạm vi platform</h3>
39
+ <p>Vì sao repo này tồn tại khi đã có agent coding tổng quát, và ranh giới nó nhận về mình.</p>
40
+ </a>
41
+ <a class="doc-card" href="/profiles">
42
+ <span class="card-kicker">Build</span>
43
+ <h3>Project profile</h3>
44
+ <p>Chọn đường ray cho repo: protected path, verify command, capability được cấp.</p>
45
+ </a>
46
+ <a class="doc-card" href="/mcp">
47
+ <span class="card-kicker">MCP</span>
48
+ <h3>MCP</h3>
49
+ <p>Bốn layer config, preset đã pin, quản lý server, trạng thái auth, và approval gate cho server đến từ repo.</p>
50
+ </a>
51
+ <a class="doc-card" href="/security">
52
+ <span class="card-kicker">Operate</span>
53
+ <h3>Security model</h3>
54
+ <p>Policy enforcement layer chứ không phải OS sandbox — nói rõ chặn được gì và không chặn được gì.</p>
55
+ </a>
56
+ <a class="doc-card" href="/commands">
57
+ <span class="card-kicker">Build</span>
58
+ <h3>Command catalog</h3>
59
+ <p>Slash command và terminal command, nhóm theo việc cần làm.</p>
60
+ </a>
61
+ </div>
62
+ </section>
63
+
64
+ <section class="section">
65
+ <h2 id="ba-nhom">Tài liệu chia làm ba nhóm</h2>
66
+ <div class="split">
67
+ <div class="card">
68
+ <h3 id="get-started-nhom">Get started</h3>
69
+ <p>Dành cho người chưa chạy lần nào: cài, quickstart, và vị trí của platform so với các agent CLI khác.</p>
70
+ </div>
71
+ <div class="card">
72
+ <h3 id="build-nhom">Build</h3>
73
+ <p>Dùng hằng ngày: profile, permission, command, workflow — và MCP tách riêng vì có bề mặt lệnh của nó.</p>
74
+ </div>
75
+ <div class="card">
76
+ <h3 id="operate-nhom">Operate</h3>
77
+ <p>Người vận hành và review: security model, kiến trúc repo, terminal tool, cách team dùng như một chuẩn.</p>
78
+ </div>
79
+ </div>
80
+ </section>
package/docs-site/content/mcp-approval.html ADDED
@@ -0,0 +1,81 @@
1
+ <section class="section">
2
+ <h2 id="van-de">Vấn đề</h2>
3
+ <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>
4
+
5
+ <pre><code>/piagent-mcp get internal # đọc trước
6
+ /piagent-mcp approve internal # hoặc reject, hoặc reset</code></pre>
7
+
8
+ <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>
9
+
10
+ <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>
11
+ </section>
12
+
13
+ <section class="section">
14
+ <h2 id="ba-tinh-chat">Ba tính chất</h2>
15
+
16
+ <div class="grid">
17
+ <div class="card">
18
+ <h3 id="ngoai-repo">Quyết định nằm ngoài repo</h3>
19
+ <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>
20
+ </div>
21
+ <div class="card">
22
+ <h3 id="pin-digest">Pin theo digest</h3>
23
+ <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>
24
+ </div>
25
+ <div class="card">
26
+ <h3 id="enforce-tool-call">Enforce ở tool call</h3>
27
+ <p>Guard chặn cả proxy (<span class="inline-code">mcp</span> với <span class="inline-code">input.server</span>) lẫn dạng direct tool (<span class="inline-code">mcp__&lt;server&gt;__&lt;tool&gt;</span>). Gate chỉ đọc proxy sẽ bị đi vòng bằng cách bật <span class="inline-code">directTools</span>.</p>
28
+ </div>
29
+ </div>
30
+ </section>
31
+
32
+ <section class="section">
33
+ <h2 id="gioi-han">Giới hạn</h2>
34
+
35
+ <div class="callout">
36
+ <strong>Không chặn được connection</strong>
37
+ <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>
38
+ </div>
39
+
40
+ <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>
41
+ </section>
42
+
43
+ <section class="section">
44
+ <h2 id="thiet-ke">Bốn quyết định thiết kế</h2>
45
+
46
+ <div class="table-wrap">
47
+ <table>
48
+ <thead>
49
+ <tr><th>Quyết định</th><th>Vì sao</th></tr>
50
+ </thead>
51
+ <tbody>
52
+ <tr>
53
+ <td>Chỉ gate server đến từ repo</td>
54
+ <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>
55
+ </tr>
56
+ <tr>
57
+ <td>Quyết định lưu ngoài repo</td>
58
+ <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>
59
+ </tr>
60
+ <tr>
61
+ <td>Pin theo digest của định nghĩa</td>
62
+ <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>
63
+ </tr>
64
+ <tr>
65
+ <td>Chặn ở <span class="inline-code">tool_call</span></td>
66
+ <td>Cả dạng proxy <span class="inline-code">mcp</span> lẫn dạng direct <span class="inline-code">mcp__&lt;server&gt;__&lt;tool&gt;</span>, để không có đường vòng.</td>
67
+ </tr>
68
+ </tbody>
69
+ </table>
70
+ </div>
71
+
72
+ <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>
73
+ </section>
74
+
75
+ <section class="section">
76
+ <h2 id="migration">Migration</h2>
77
+ <div class="callout">
78
+ <strong>Project đã có server từ trước</strong>
79
+ <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>
80
+ </div>
81
+ </section>