@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
  1. package/CHANGELOG.md +175 -1
  2. package/README.md +2 -2
  3. package/docs/command-reference-vietnamese.md +19 -5
  4. package/docs/distribution-standard.md +7 -7
  5. package/docs/mcp-and-tools.md +154 -2
  6. package/docs/model-options.md +10 -8
  7. package/docs/operator-manual-vietnamese.md +25 -13
  8. package/docs/publishing-for-teams.md +2 -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 +4 -3
  12. package/docs/team-onboarding.md +4 -4
  13. package/docs/usage-observability.md +29 -0
  14. package/docs/vercel-docs-site.md +34 -4
  15. package/docs-site/architecture.html +152 -0
  16. package/docs-site/assets/docs.css +1001 -0
  17. package/docs-site/assets/docs.js +84 -0
  18. package/docs-site/commands.html +203 -0
  19. package/docs-site/content/architecture.html +29 -0
  20. package/docs-site/content/commands.html +80 -0
  21. package/docs-site/content/index.html +80 -0
  22. package/docs-site/content/mcp-approval.html +133 -0
  23. package/docs-site/content/mcp-auth.html +76 -0
  24. package/docs-site/content/mcp-servers.html +111 -0
  25. package/docs-site/content/mcp.html +120 -0
  26. package/docs-site/content/permissions.html +54 -0
  27. package/docs-site/content/profiles.html +68 -0
  28. package/docs-site/content/quickstart.html +144 -0
  29. package/docs-site/content/runtime.html +45 -0
  30. package/docs-site/content/scope.html +71 -0
  31. package/docs-site/content/security.html +51 -0
  32. package/docs-site/content/team.html +23 -0
  33. package/docs-site/content/workflows.html +47 -0
  34. package/docs-site/index.html +131 -1534
  35. package/docs-site/mcp-approval.html +256 -0
  36. package/docs-site/mcp-auth.html +199 -0
  37. package/docs-site/mcp-servers.html +234 -0
  38. package/docs-site/mcp.html +243 -0
  39. package/docs-site/permissions.html +177 -0
  40. package/docs-site/profiles.html +191 -0
  41. package/docs-site/quickstart.html +267 -0
  42. package/docs-site/runtime.html +168 -0
  43. package/docs-site/scope.html +194 -0
  44. package/docs-site/security.html +174 -0
  45. package/docs-site/team.html +142 -0
  46. package/docs-site/workflows.html +170 -0
  47. package/package.json +4 -2
  48. package/packages/piagent-core/capabilities/capability-core.js +58 -5
  49. package/packages/piagent-core/capabilities/capability-sources.js +73 -12
  50. package/packages/piagent-core/extensions/document-intake.ts +5 -5
  51. package/packages/piagent-core/extensions/piagent-guard.ts +432 -2
  52. package/packages/piagent-core/extensions/policy-core.js +1586 -98
  53. package/packages/piagent-core/mcp/mcp-approval-store.js +216 -0
  54. package/packages/piagent-core/mcp/mcp-auth-readiness.js +225 -0
  55. package/packages/piagent-core/mcp/mcp-command-actions.js +400 -0
  56. package/packages/piagent-core/mcp/mcp-config-layers.js +466 -0
  57. package/packages/piagent-core/mcp/mcp-import-kinds.js +240 -0
  58. package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
  59. package/packages/piagent-core/mcp/mcp-server-entry.js +293 -0
  60. package/packages/piagent-core/mcp/mcp-session-view.js +236 -0
  61. package/packages/piagent-core/mcp/mcp-tool-naming.js +90 -0
  62. package/packages/piagent-core/package.json +7 -3
  63. package/packages/piagent-core/prompts/model-options.md +8 -8
  64. package/scripts/build-docs-site.mjs +421 -0
  65. package/scripts/configure-model-scope.sh +21 -5
  66. package/scripts/configure-subagents.sh +18 -5
  67. package/scripts/init-project.sh +15 -8
  68. package/scripts/install-global.sh +5 -5
  69. package/scripts/mcp-manage.mjs +656 -0
  70. package/scripts/pi-model-catalog.sh +11 -1
  71. package/scripts/pi-session-stats.sh +27 -1
  72. package/scripts/pi-usage-history.mjs +567 -0
  73. package/scripts/piagent-cli.mjs +1 -1
  74. package/scripts/preview-docs-site.mjs +88 -0
  75. package/scripts/quality-benchmark.sh +37 -9
  76. package/scripts/setup.sh +23 -15
  77. package/scripts/team-doctor.sh +18 -2
  78. package/scripts/uninstall-global.sh +10 -4
  79. package/scripts/verify-local.sh +65 -19
  80. package/scripts/verify-release-identity.mjs +37 -2
  81. 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.1 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,133 @@
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 đọ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>
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="imports">Server đến qua <span class="inline-code">imports</span></h2>
45
+
46
+ <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>
47
+
48
+ <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>
49
+
50
+ <div class="table-wrap">
51
+ <table>
52
+ <thead>
53
+ <tr><th>Tình huống</th><th>Xử lý</th></tr>
54
+ </thead>
55
+ <tbody>
56
+ <tr>
57
+ <td>Layer bất kỳ import kind repo-relative</td>
58
+ <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>
59
+ </tr>
60
+ <tr>
61
+ <td>Repo scope import kind bất kỳ</td>
62
+ <td>Server phải duyệt. Repo đang chọn hộ máy này chạy server nào.</td>
63
+ </tr>
64
+ <tr>
65
+ <td>Repo scope import kind không đọc được nội dung (<span class="inline-code">codex</span>, TOML)</td>
66
+ <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>
67
+ </tr>
68
+ <tr>
69
+ <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>
70
+ <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>
71
+ </tr>
72
+ <tr>
73
+ <td><span class="inline-code">directTools</span> + <span class="inline-code">toolPrefix: "none"</span> trong config repo mang theo</td>
74
+ <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>
75
+ </tr>
76
+ </tbody>
77
+ </table>
78
+ </div>
79
+
80
+ <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>
81
+
82
+ <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>
83
+
84
+ <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>
85
+
86
+ <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>
87
+
88
+ <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>
89
+ </section>
90
+
91
+ <section class="section">
92
+ <h2 id="thiet-ke">Bốn quyết định thiết kế</h2>
93
+
94
+ <div class="table-wrap">
95
+ <table>
96
+ <thead>
97
+ <tr><th>Quyết định</th><th>Vì sao</th></tr>
98
+ </thead>
99
+ <tbody>
100
+ <tr>
101
+ <td>Chỉ gate server đến từ repo</td>
102
+ <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>
103
+ </tr>
104
+ <tr>
105
+ <td>Quyết định lưu ngoài repo</td>
106
+ <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>
107
+ </tr>
108
+ <tr>
109
+ <td>Pin theo digest của định nghĩa</td>
110
+ <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>
111
+ </tr>
112
+ <tr>
113
+ <td>Preview in ra bản đã merge, digest tính trên mảnh của repo</td>
114
+ <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>
115
+ </tr>
116
+ <tr>
117
+ <td>Chặn ở <span class="inline-code">tool_call</span></td>
118
+ <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>
119
+ </tr>
120
+ </tbody>
121
+ </table>
122
+ </div>
123
+
124
+ <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>
125
+ </section>
126
+
127
+ <section class="section">
128
+ <h2 id="migration">Migration</h2>
129
+ <div class="callout">
130
+ <strong>Project đã có server từ trước</strong>
131
+ <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>
132
+ </div>
133
+ </section>