@piagent/platform 1.2.12 → 1.2.14

package/docs-site/architecture.html

@@ -27,7 +27,8 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.2.12 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.2.14 docs · VI</span>
+        <a class="button" href="https://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
         <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" />
@@ -74,6 +75,7 @@
             <a class="nav-link" href="/security">Security model</a>
             <a class="nav-link current" href="/architecture" aria-current="page">Architecture</a>
             <a class="nav-link" href="/context-engine">Context Engine</a>
+            <a class="nav-link" href="/benchmark">Benchmark</a>
             <a class="nav-link" href="/runtime">Runtime tools</a>
             <a class="nav-link" href="/team">Team usage</a>
           </div>
@@ -94,34 +96,56 @@
               <p>Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được.</p>
             </div>
 <section class="section">
-
+  <div class="callout">
+    <strong>Chiều dependency được enforce bằng code.</strong>
+    <p><span class="inline-code">architecture/layers.json</span> là rule máy đọc; <span class="inline-code">npm run architecture:check</span> chặn dependency ngược và file vượt budget.</p>
+  </div>
   <div class="grid cols-3">
     <article class="card">
-      <h3 id="core-package">Core package</h3>
-      <p><span class="inline-code">packages/piagent-core</span> chứa extension guard, prompts, skills và subagent roles.</p>
+      <h3 id="composition">Composition</h3>
+      <p><span class="inline-code">piagent-guard.ts</span> chỉ giữ wiring, registration order và shared runtime state. File này không được tiếp tục chứa feature algorithm.</p>
     </article>
     <article class="card">
-      <h3 id="adapters">Adapters</h3>
-      <p><span class="inline-code">adapters/</span> chứa profile dùng lại: frontend, backend, fullstack, data, devops, docs.</p>
+      <h3 id="runtime-adapters">Runtime adapters</h3>
+      <p><span class="inline-code">packages/piagent-core/runtime</span> quản lý Pi hook, command, tool, session UI, usage, log compaction và workflow input routing.</p>
     </article>
     <article class="card">
-      <h3 id="capability-packs">Capability packs</h3>
-      <p><span class="inline-code">packs/</span> gom policy, lifecycle, recipes và eval scenarios theo manifest có lock.</p>
+      <h3 id="core-services">Core services</h3>
+      <p>Policy, task, context và state trả về structured decision. Core service không import runtime adapter hay Pi composition root.</p>
     </article>
     <article class="card">
-      <h3 id="policies">Policies</h3>
-      <p>Base policy định nghĩa protected paths, command rules, permission modes và human-action gates.</p>
+      <h3 id="integrations">Integrations</h3>
+      <p><span class="inline-code">mcp/</span>, <span class="inline-code">capabilities/</span> và <span class="inline-code">security/</span> có ownership riêng; không nhúng task workflow vào integration.</p>
     </article>
     <article class="card">
-      <h3 id="scripts">Scripts</h3>
-      <p>Setup, doctor, model scope, MCP, subagents, benchmark và trusted-run wrapper đều có CLI riêng.</p>
+      <h3 id="entrypoints">Entrypoints</h3>
+      <p><span class="inline-code">scripts/</span> parse CLI argument rồi gọi use case. Metric, policy và state transition không được duplicate trong CLI.</p>
     </article>
     <article class="card">
-      <h3 id="docs">Docs</h3>
-      <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>
+      <h3 id="product-assets">Product assets</h3>
+      <p><span class="inline-code">prompts/</span>, <span class="inline-code">skills/</span>, <span class="inline-code">subagents/</span>, <span class="inline-code">adapters/</span>, <span class="inline-code">packs/</span> và <span class="inline-code">schemas/</span> là declarative assets.</p>
     </article>
   </div>
 </section>
+
+<section class="section">
+  <div class="section-head">
+    <p class="eyebrow">Ownership</p>
+    <h2 id="state-ownership">Một state chỉ có một source of truth</h2>
+    <p>Project profile và lock có thể commit. Task evidence, telemetry, trace, capture và session history là local state. Derived index phải có policy digest và rebuild được.</p>
+  </div>
+  <div class="table-wrap">
+    <table>
+      <thead><tr><th>State</th><th>Owner</th><th>Vị trí</th><th>Commit</th></tr></thead>
+      <tbody>
+        <tr><td>Project profile + lock</td><td>Project</td><td><span class="inline-code">.pi/piagent-profile*.json</span></td><td>Có</td></tr>
+        <tr><td>Task, trace, telemetry, capture</td><td>Runtime</td><td><span class="inline-code">.pi/piagent-state/</span></td><td>Không</td></tr>
+        <tr><td>Session history</td><td>Pi</td><td>Pi session store</td><td>Không</td></tr>
+        <tr><td>Shared instructions</td><td>Project</td><td><span class="inline-code">AGENTS.md</span>, project docs</td><td>Có</td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
             <nav class="pager" aria-label="Trang kế tiếp">
               <a class="pager-prev" href="/security">
                 <span class="pager-label">Trước</span>
@@ -138,6 +162,7 @@
               <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://github.com/Vt-mmm/piagent/blob/main/docs/en/README.md" lang="en" target="_blank" rel="noopener noreferrer">English docs</a>
                 <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
               </div>
             </footer>

package/docs-site/assets/docs.css

@@ -14,6 +14,8 @@
   --danger: #ff8f8f;
   --warning: #ffd166;
   --ok: #8be9c8;
+  --chart-piagent: #8be9c8;
+  --chart-codex: #8fa7ff;
   --shadow: 0 24px 90px rgba(0, 0, 0, 0.45);
   --radius: 22px;
   --sidebar: 294px;
@@ -978,6 +980,411 @@ tr:last-child td {
   color: var(--accent);
 }
 
+/* Production benchmark snapshot. The charts are plain CSS so the evidence is
+   readable in the committed static HTML without a client charting runtime. */
+.benchmark-summary {
+  padding: 28px 0 12px;
+  border-top: 1px solid var(--line);
+  border-bottom: 1px solid var(--line);
+}
+
+.benchmark-verdict {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 180px;
+  gap: 32px;
+  align-items: center;
+}
+
+.benchmark-verdict h2 {
+  font-size: 36px;
+  letter-spacing: 0;
+}
+
+.benchmark-verdict p:last-child {
+  max-width: 780px;
+  margin-top: 12px;
+}
+
+.benchmark-verdict-score {
+  padding-left: 24px;
+  border-left: 1px solid var(--line);
+}
+
+.benchmark-verdict-score strong {
+  display: block;
+  color: var(--accent);
+  font-size: 48px;
+  line-height: 1;
+  letter-spacing: 0;
+}
+
+.benchmark-verdict-score span {
+  display: block;
+  margin-top: 8px;
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.benchmark-metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  margin-top: 28px;
+  border-top: 1px solid var(--line-soft);
+}
+
+.benchmark-metric {
+  min-width: 0;
+  padding: 18px 18px 14px 0;
+}
+
+.benchmark-metric + .benchmark-metric {
+  padding-left: 18px;
+  border-left: 1px solid var(--line-soft);
+}
+
+.benchmark-metric span,
+.benchmark-metric small {
+  display: block;
+  color: var(--muted-2);
+  font-size: 12px;
+}
+
+.benchmark-metric strong {
+  display: block;
+  margin: 5px 0 3px;
+  color: var(--text);
+  font-size: 24px;
+  line-height: 1.2;
+  letter-spacing: 0;
+}
+
+.benchmark-facts {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0 24px;
+  margin: 28px 0 0;
+}
+
+.benchmark-facts div {
+  min-width: 0;
+  padding: 14px 0;
+  border-bottom: 1px solid var(--line-soft);
+}
+
+.benchmark-facts dt {
+  color: var(--muted-2);
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.benchmark-facts dd {
+  margin: 5px 0 0;
+  color: var(--text);
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+
+.benchmark-score-chart {
+  display: grid;
+  gap: 13px;
+  margin-top: 30px;
+  padding: 22px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel);
+}
+
+.benchmark-score-row,
+.benchmark-usage-row {
+  display: grid;
+  grid-template-columns: 112px minmax(120px, 1fr) 64px;
+  gap: 14px;
+  align-items: center;
+}
+
+.benchmark-score-row > span,
+.benchmark-usage-row > span {
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.benchmark-score-row strong,
+.benchmark-usage-row strong {
+  color: var(--text);
+  font-family: "JetBrains Mono", monospace;
+  font-size: 12px;
+  text-align: right;
+}
+
+.benchmark-track {
+  position: relative;
+  width: 100%;
+  height: 10px;
+  overflow: hidden;
+  border-radius: 5px;
+  background: #24262d;
+}
+
+.benchmark-track i,
+.benchmark-win-track i {
+  display: block;
+  width: var(--bar-size);
+  height: 100%;
+}
+
+.benchmark-score-row .benchmark-track i {
+  background: var(--chart-piagent);
+}
+
+.benchmark-score-row.overall {
+  padding-top: 13px;
+  border-top: 1px solid var(--line-soft);
+}
+
+.benchmark-score-row.overall .benchmark-track i {
+  background: var(--accent);
+}
+
+.benchmark-table-wrap code {
+  overflow-wrap: anywhere;
+}
+
+.benchmark-table-wrap {
+  border-radius: 8px;
+}
+
+.benchmark-table-wrap td strong {
+  color: var(--accent);
+}
+
+.benchmark-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 18px;
+  margin-top: 28px;
+}
+
+.benchmark-legend span {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.benchmark-legend i {
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+}
+
+.piagent-swatch,
+.piagent-bar,
+.piagent-win {
+  background: var(--chart-piagent);
+}
+
+.codex-swatch,
+.codex-bar,
+.codex-win {
+  background: var(--chart-codex);
+}
+
+.benchmark-usage-chart {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 28px 34px;
+  margin-top: 18px;
+  padding: 24px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel);
+}
+
+.benchmark-usage-group h3 {
+  margin-bottom: 14px;
+  font-size: 14px;
+  letter-spacing: 0;
+}
+
+.benchmark-usage-row {
+  grid-template-columns: 78px minmax(80px, 1fr) 62px;
+  gap: 10px;
+}
+
+.benchmark-usage-row + .benchmark-usage-row {
+  margin-top: 9px;
+}
+
+.benchmark-paired {
+  margin-top: 28px;
+  padding: 22px;
+  border-left: 3px solid var(--chart-piagent);
+  background: rgba(139, 233, 200, 0.045);
+}
+
+.benchmark-paired-head {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 20px;
+}
+
+.benchmark-paired-head span,
+.benchmark-paired-head strong {
+  display: block;
+}
+
+.benchmark-paired-head span {
+  color: var(--muted-2);
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.benchmark-paired-head strong {
+  margin-top: 4px;
+  color: var(--text);
+  font-size: 15px;
+}
+
+.benchmark-win-track {
+  display: flex;
+  width: 100%;
+  height: 14px;
+  margin: 18px 0;
+  overflow: hidden;
+  border-radius: 7px;
+  background: #24262d;
+}
+
+.benchmark-paired p strong {
+  color: var(--text);
+}
+
+.benchmark-categories {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  margin-top: 28px;
+}
+
+.benchmark-categories > div {
+  position: relative;
+  min-width: 0;
+  padding: 18px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--panel);
+}
+
+.benchmark-categories span {
+  color: var(--muted-2);
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.benchmark-categories strong {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  color: var(--accent);
+  font-family: "JetBrains Mono", monospace;
+  font-size: 14px;
+}
+
+.benchmark-categories p {
+  margin-top: 10px;
+  padding-right: 40px;
+  font-size: 13px;
+}
+
+@media (max-width: 920px) {
+  .benchmark-metrics,
+  .benchmark-categories {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .benchmark-metric:nth-child(3) {
+    padding-left: 0;
+    border-left: 0;
+  }
+
+  .benchmark-facts,
+  .benchmark-usage-chart {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 760px) {
+  .benchmark-verdict {
+    grid-template-columns: 1fr;
+    gap: 22px;
+  }
+
+  .benchmark-verdict-score {
+    padding: 0;
+    border-left: 0;
+  }
+
+  .benchmark-verdict-score strong {
+    font-size: 42px;
+  }
+
+  .benchmark-score-chart,
+  .benchmark-usage-chart,
+  .benchmark-paired {
+    padding: 16px;
+  }
+
+  .benchmark-score-row {
+    grid-template-columns: 88px minmax(70px, 1fr) 54px;
+    gap: 8px;
+  }
+
+  .benchmark-paired-head {
+    grid-template-columns: 1fr;
+  }
+
+  .benchmark-table-wrap {
+    overflow-x: auto;
+  }
+
+  .benchmark-table-wrap table {
+    min-width: 680px;
+  }
+
+  .benchmark-table-wrap th,
+  .benchmark-table-wrap td {
+    display: table-cell;
+    width: auto;
+    padding: 12px;
+  }
+}
+
+@media (max-width: 520px) {
+  .benchmark-metrics,
+  .benchmark-categories {
+    grid-template-columns: 1fr;
+  }
+
+  .benchmark-metric,
+  .benchmark-metric + .benchmark-metric,
+  .benchmark-metric:nth-child(3) {
+    padding: 14px 0;
+    border-left: 0;
+    border-bottom: 1px solid var(--line-soft);
+  }
+
+  .benchmark-usage-row {
+    grid-template-columns: 72px minmax(60px, 1fr) 56px;
+  }
+}
+
 /* An anchor target under a sticky header lands with its heading hidden. */
 .section[id],
 h2[id],