@piagent/platform 1.4.0 → 1.4.1

package/docs/runtime-harness-standard.md

@@ -87,7 +87,7 @@ tool context mang tính advisory chỉ được nạp khi task thực sự cần
 
 ```text
 1. Intake
-   - one Pi session per task
+   - one pending task per Pi session; terminal tasks remain immutable while the conversation may continue with a successor task
    - runtime auto-start for bounded source changes; manual fallback for broad/high-risk/ambiguous scope
    - source-change or read-only
    - risk lane

package/docs/security-threat-model.md

@@ -25,7 +25,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.4.0, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.4.1, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/task-implementation-contract.md

@@ -20,7 +20,7 @@ Agent Watch/report hien ten task ma operator da dat.
 | Nhom | Field | Quy tac |
 |---|---|---|
 | Schema | `schemaVersion` | Luon la `2`. |
-| Identity | `taskRunId`, `taskId`, `sessionId`, `sessionName`, `intakeMode` | Run ID/Task ID normalized; mot session chi co mot task; intake la `runtime` hoac `model`. |
+| Identity | `taskRunId`, `taskId`, `sessionId`, `sessionName`, `intakeMode` | Run ID/Task ID normalized; mot session chi co mot task pending, nhung co the chua nhieu task terminal tuan tu; intake la `runtime` hoac `model`. |
 | Mode | `changeMode` | `source-change` hoac `read-only`. |
 | Retry | `attempt`, `maxAttempts`, `previousAttempts` | Tran lay tu attempt dau, khong duoc nang o retry sau. |
 | Intent | `summary`, `riskLane`, `expectedOutput`, `acceptanceCriteria` | Chot truoc khi implementation. |
@@ -32,6 +32,11 @@ Agent Watch/report hien ten task ma operator da dat.
 | Outcome | `trace`, `failedAt`, `failureReason`, `ruledOut` | Terminal contract immutable. |
 | Time | `createdAt`, `updatedAt` | Timestamp parseable, dung de sap xep/migration/report. |
 
+`source-change` la mode co quyen thuc thi command cua project, khong phai loi
+khai rang task bat buoc sua source. Yeu cau chi chay test/build/lint/typecheck
+hoac package dry-run van dung mode nay va co the hoan tat voi working tree khong
+doi. `read-only` danh cho inspection khong can shell execution.
+
 Template day du nam tai
 [`templates/project/.pi/task-contract.template.json`](../templates/project/.pi/task-contract.template.json).
 Schema chinh thuc nam tai
@@ -56,7 +61,7 @@ context/verify/trace/gate tools are recovery surfaces for custom/high-risk work.
 
 Task start tu choi khi:
 
-- session da thuoc task khac hoac task terminal;
+- session dang co mot task pending khac;
 - cung `taskId` dang pending o session khac;
 - task da completed;
 - retry vuot `maxAttempts`;
@@ -111,8 +116,10 @@ failed step can note moi; step done/skipped khong duoc mo lai. Khi trace da
 terminal, cac tool progress/context/memory/verify/trace va project mutations deu
 bi chan cho session do.
 
-Retry chay o session moi. `previousAttempts` giu outcome, phase failure, reason,
-ruled-out hypothesis va timestamp de agent khong lap lai cach da that bai.
+Retry co the chay tiep trong cung session sau khi attempt truoc da terminal.
+`previousAttempts` giu outcome, phase failure, reason, ruled-out hypothesis va
+timestamp de agent khong lap lai cach da that bai. Session binding luon tro den
+task moi nhat; task terminal cu van immutable va con nguyen evidence.
 
 ## Migration v1 -> v2
 

package/docs/team-onboarding.md

@@ -10,7 +10,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.4.0
+npm install -g --ignore-scripts @piagent/platform@1.4.1
 piagent-install --stable
 cd /path/to/project
 pi
@@ -44,7 +44,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.4.0
+npm install -g --ignore-scripts @piagent/platform@1.4.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs/usage-observability.md

@@ -183,6 +183,76 @@ Format hỗ trợ:
 | CSV | `piagent-usage --history <project> --csv` |
 | Markdown | `piagent-usage --history <project> --markdown` |
 
+### Shape của `--json`
+
+Table/CSV/Markdown chỉ in một phần report. `--json` trả nguyên object, gồm **6 key top-level**:
+
+| Key | Nội dung |
+|---|---|
+| `generatedAt` | ISO timestamp lúc chạy lệnh. Dùng để so hai report với nhau. |
+| `scope` | `projectPath` (null khi `--all-projects`), `allProjects`, `includeSubagents`, `sessionsDir`, `since`, `until`. Đây là bản ghi chính xác của filter đã áp — report không tự giải thích được nếu thiếu key này. |
+| `totals` | `sessions` / `mainSessions` / `subagentSessions`, `messages` (`user`, `assistant`, `toolCalls`, `toolResults`, `total`), `promptChars`, và `tokens` (xem bảng "Cách đọc số"). |
+| `projects` | Một dòng cho mỗi `cwd`, sort giảm dần theo `tokens.total`: `cwd`, `sessions`, `mainSessions`, `subagentSessions`, `tokens`, `cost`. |
+| `tools` | `{ name, count }` cho mỗi tool đã gọi, sort giảm dần theo `count`. Đây là chỗ nhìn ra tool nào đang đốt tool-call budget. |
+| `sessions` | Một dòng cho mỗi session, mới nhất trước: `id`, `name`, `cwd`, `file`, `isSubagent`, `provider`, `modelId`, `thinkingLevel`, `firstTimestamp`, `lastTimestamp`, `messages`, `tokens`. |
+
+Mọi `Date` đều được serialize thành ISO string, nên output an toàn để `jq` hoặc
+đẩy thẳng vào báo cáo.
+
+```bash
+# Top 10 tool tốn nhiều call nhất trong 7 ngày, toàn máy
+piagent-usage --history --all-projects --days 7 --json | jq '.tools[:10]'
+
+# Cost theo từng project
+piagent-usage --history --all-projects --days 7 --json | jq '.projects[] | {cwd, cost}'
+```
+
+## Đo lượt dùng từ bên ngoài
+
+Ba kênh khác nhau, ba bộ đếm khác nhau — **không cộng vào nhau**:
+
+| Kênh | Đếm gì | Lấy ở đâu |
+|---|---|---|
+| npm downloads | cài qua `npm install` | `api.npmjs.org/downloads/point/last-week/@piagent/platform` |
+| GitHub clones | cài qua `pi install git:…` (mỗi lần là một `git clone`) | `gh api repos/<owner>/<repo>/traffic/clones` |
+| Docs site | người đọc tài liệu | Vercel Web Analytics |
+
+Đọc số npm cẩn thận: với package còn mới, mirror và scanner chiếm phần lớn.
+Dấu hiệu nhận ra là **phân bổ đều giữa nhiều version**, kể cả prerelease cũ —
+người thật dồn vào bản mới nhất, bot thì kéo tất.
+
+### Traffic GitHub chỉ sống 14 ngày
+
+API traffic chỉ trả cửa sổ trượt 14 ngày và **xoá hẳn** phần cũ hơn: không có
+endpoint nào lấy lại được. Workflow `traffic-snapshot` chạy hằng ngày và gộp
+vào CSV cộng dồn trên nhánh `traffic-data`, nên lịch sử không mất. Khoảng trống
+dài hơn 14 ngày là vĩnh viễn.
+
+```bash
+# chạy tay, ghi vào ./traffic
+TRAFFIC_TOKEN="$(gh auth token)" node scripts/traffic-snapshot.mjs --repository Vt-mmm/piagent
+```
+
+Traffic endpoint đòi quyền **push** trên repo. Nếu `GITHUB_TOKEN` mặc định của
+Actions không đủ, script sẽ báo `HTTP 403` kèm đúng cách sửa: tạo fine-grained
+PAT có quyền `Administration: read` rồi lưu thành secret `TRAFFIC_TOKEN`.
+
+### Docs site
+
+Site dùng **Vercel Web Analytics** — cookieless, không lưu định danh trên
+trình duyệt, nên không cần banner đồng ý. Snippet nằm trong shell của
+`build-docs-site.mjs` nên mọi trang và cả hai ngôn ngữ đều có; test chặn
+trường hợp thêm trang mới mà quên.
+
+Phải bật trong Vercel dashboard (**Analytics → Enable**) rồi deploy lại thì
+route `/_vercel/insights/*` mới tồn tại. Trước đó request 404 và trang vẫn chạy
+bình thường.
+
+Runtime của piagent **không gửi gì ra ngoài**: `telemetry()` ghi local qua
+`appendContextTelemetry(cwd, …)`, package không có `postinstall`. Đó là chủ ý —
+một sản phẩm bán bằng lời hứa owner-only local state thì không nên có lệnh gọi
+mạng ngầm.
+
 ## Cách đọc số
 
 | Field | Ý nghĩa |

package/docs/vi/architecture.md

@@ -43,9 +43,22 @@ Rule máy đọc nằm tại `architecture/layers.json`; chạy `npm run archite
 | Capabilities | `packages/piagent-core/capabilities/` | Profile resolution, pack validation, lock, source root | Pi session lifecycle |
 | Security foundation | `packages/piagent-core/security/` | Sensitive-data primitive | Workflow behavior |
 | Benchmark | `packages/piagent-core/benchmark/`, `benchmarks/` | Suite validation, scoring, evidence | Runtime enforcement |
+| WebUI contracts | `packages/piagent-webui/contracts/` | Wire type dùng chung giữa browser và server | Mọi hành vi runtime; layer này không phụ thuộc gì |
+| WebUI client | `packages/piagent-webui/client/` | View trên browser, view model, UI preference | Server state, filesystem, Pi API |
+| WebUI server | `packages/piagent-webui/server/` | HTTP/WS endpoint, đọc session, dựng diff | Render phía browser; không được import client |
+| WebUI extension | `packages/piagent-webui/extension/` | Lệnh `/piagent-webui` chạy trong Pi | Wire type mà client cũng cần |
+| WebUI gateway | `packages/piagent-webui/gateway/` | Tiến trình `piagent dashboard` độc lập, port và lifecycle | Feature logic thuộc về server |
+| WebUI ownership | `packages/piagent-webui/ownership/` | Claim single-owner trên một session directory | Transport và render; layer này không phụ thuộc gì |
+| WebUI build | `packages/piagent-webui/` (gốc package) | Bundle client và đóng gói asset được serve | Source của bất kỳ WebUI layer nào |
 | Entrypoints | `scripts/` | CLI argument và gọi use case | Domain logic trùng lặp |
 | Product assets | `prompts/`, `skills/`, `subagents/`, `adapters/`, `packs/`, `schemas/` | Declarative behavior và contract | Hidden runtime state |
 
+Các layer WebUI là một trục dependency thứ hai, không phải nhánh của trục đầu. `contracts` và
+`ownership` nằm dưới cùng và không import gì; `client` chỉ được với tới `contracts`, nên bundle
+browser không bao giờ kéo theo code server hay Pi. `server`, `extension`, `gateway` với xuống
+`runtime`/`core`/`security` — không bao giờ ngược lại, nên platform vẫn chạy headless khi không
+có WebUI. `npm run architecture:check` enforce toàn bộ edge trên.
+
 Folder `extensions/` vẫn chứa một số service module do lịch sử. Tên folder này là legacy; chỉ `piagent-guard.ts` được Pi load như extension. Mỗi lần migrate phải tách theo một feature trọn vẹn và giữ compatibility cho đến khi migration hoàn tất.
 
 ## Luồng runtime

package/docs-site/architecture.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/architecture" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/architecture" hreflang="en" lang="en">EN</a>
@@ -217,5 +217,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/benchmark.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/benchmark" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/benchmark" hreflang="en" lang="en">EN</a>
@@ -364,5 +364,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/commands.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/commands" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/commands" hreflang="en" lang="en">EN</a>
@@ -254,5 +254,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/content/en/index.html

@@ -18,6 +18,55 @@
   </div>
 </section>
 
+<section class="section">
+  <p class="section-kicker">Production V1 · historical public regression evidence</p>
+  <h2 id="evidence">Measured, not asserted</h2>
+  <p class="section-lead">108 sessions on the same model and thinking level, graded automatically, against an isolated <code>codex-cli</code> surface. This is the production-v1 measurement; it is not a re-measurement of v1.4.0.</p>
+
+  <div class="benchmark-metrics" aria-label="Headline benchmark numbers">
+    <div class="benchmark-metric">
+      <span>Overall</span>
+      <strong>9.92 / 10</strong>
+      <small>Quality, Safety, Reliability all 10/10</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Tasks resolved</span>
+      <strong>54/54</strong>
+      <small>100% on both surfaces</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Fresh tokens</span>
+      <strong>-51.11%</strong>
+      <small>paired geometric mean, 47/54 pair wins</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Infrastructure</span>
+      <strong>0 retries</strong>
+      <small>108 valid runs</small>
+    </div>
+  </div>
+
+  <div class="benchmark-legend" aria-label="Chart legend">
+    <span><i class="piagent-swatch"></i>Piagent</span>
+    <span><i class="codex-swatch"></i>codex-cli</span>
+  </div>
+
+  <div class="benchmark-usage-chart" aria-label="Median fresh tokens per run: Piagent 7,368, codex-cli 18,476">
+    <div class="benchmark-usage-group">
+      <h3>Fresh tokens, median per run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 39.88%"></i></div><strong>7,368</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>18,476</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Tool calls, median per run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 62.5%"></i></div><strong>5</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>8</strong></div>
+    </div>
+  </div>
+
+  <p>The 95% confidence interval on the paired ratio is <strong>0.3809–0.6276</strong>; the upper bound stays below 1.0, so the token-saving claim holds. <a href="/en/benchmark">See the full configuration, every band score, and the raw tables</a>.</p>
+</section>
+
 <section class="section">
   <h2 id="install">Install with two commands</h2>
   <p>Requires Node.js <span class="inline-code">&gt;=22.19.0</span>. Run these commands from the project you want to configure.</p>

package/docs-site/content/en/runtime.html

@@ -20,6 +20,19 @@ piagent-benchmark --production --surfaces piagent,codex-cli \
 piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></pre></article>
     <article class="command-card"><header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Copy</button></header><pre><code>piagent-capabilities catalog --check
 piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre></article>
+    <article class="command-card"><header><span>Session Hub</span><button class="clip-btn" data-clip="piagent dashboard&#10;piagent-webui --no-open">Copy</button></header><pre><code>piagent dashboard
+piagent-webui --no-open</code></pre>
+      <p class="command-note">Aliases: <code>piagent-dashboard</code>, <code>piagent-webui</code> and <code>piagent-explain</code> also work as standalone binaries.</p></article>
+    <article class="command-card"><header><span>Explain a decision</span><button class="clip-btn" data-clip="piagent explain &#39;cat .env*&#39;&#10;piagent explain --scope">Copy</button></header><pre><code>piagent explain 'cat .env*'
+piagent explain --scope</code></pre></article>
+    <article class="command-card"><header><span>Usage and tokens</span><button class="clip-btn" data-clip="piagent-usage .&#10;piagent-usage --history . --days 7">Copy</button></header><pre><code>piagent-usage .
+piagent-usage --history . --days 7</code></pre></article>
+    <article class="command-card"><header><span>Models and routing</span><button class="clip-btn" data-clip="piagent-models&#10;piagent-model-scope&#10;piagent-route">Copy</button></header><pre><code>piagent-models
+piagent-model-scope
+piagent-route</code></pre></article>
+    <article class="command-card"><header><span>Subagents and migration</span><button class="clip-btn" data-clip="piagent-subagents --preset safe&#10;piagent-migrate . --apply&#10;piagent-import-instructions">Copy</button></header><pre><code>piagent-subagents --preset safe
+piagent-migrate . --apply
+piagent-import-instructions</code></pre></article>
     <article class="command-card"><header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Copy</button></header><pre><code>npm run verify
 npm test
 npm run typecheck</code></pre></article>

package/docs-site/content/index.html

@@ -18,6 +18,55 @@
   </div>
 </section>
 
+<section class="section">
+  <p class="section-kicker">Production V1 · historical public regression evidence</p>
+  <h2 id="bang-chung">Đo được, không phải nói suông</h2>
+  <p class="section-lead">108 session, cùng model và cùng thinking level, chấm tự động, so với surface <code>codex-cli</code> chạy cách ly. Đây là bằng chứng của bản đo production-v1, không phải phép đo lại của v1.4.0.</p>
+
+  <div class="benchmark-metrics" aria-label="Số liệu benchmark nổi bật">
+    <div class="benchmark-metric">
+      <span>Overall</span>
+      <strong>9,92 / 10</strong>
+      <small>Quality, Safety, Reliability đều 10/10</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Task resolved</span>
+      <strong>54/54</strong>
+      <small>100% cho cả hai surface</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Fresh token</span>
+      <strong>-51,11%</strong>
+      <small>paired geometric mean, 47/54 cặp thắng</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Infrastructure</span>
+      <strong>0 retry</strong>
+      <small>108 lần chạy hợp lệ</small>
+    </div>
+  </div>
+
+  <div class="benchmark-legend" aria-label="Chú thích biểu đồ">
+    <span><i class="piagent-swatch"></i>Piagent</span>
+    <span><i class="codex-swatch"></i>codex-cli</span>
+  </div>
+
+  <div class="benchmark-usage-chart" aria-label="Fresh token median mỗi run: Piagent 7.368, codex-cli 18.476">
+    <div class="benchmark-usage-group">
+      <h3>Fresh token, median mỗi run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 39.88%"></i></div><strong>7.368</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>18.476</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Tool calls, median mỗi run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 62.5%"></i></div><strong>5</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>8</strong></div>
+    </div>
+  </div>
+
+  <p>Khoảng tin cậy 95% của tỷ lệ ghép cặp là <strong>0,3809–0,6276</strong>; cận trên vẫn dưới 1,0 nên claim tiết kiệm token đứng vững. <a href="/benchmark">Xem đầy đủ cấu hình, từng band điểm và bảng số</a>.</p>
+</section>
+
 <section class="section">
   <h2 id="cai-dat">Cài trong hai lệnh</h2>
   <p>Node.js <span class="inline-code">&gt;=22.19.0</span>. Chạy từ đúng project muốn set up.</p>

package/docs-site/content/runtime.html

@@ -50,6 +50,34 @@ piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></p
       <header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Lấy lệnh</button></header>
       <pre><code>piagent-capabilities catalog --check
 piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Session Hub</span><button class="clip-btn" data-clip="piagent dashboard&#10;piagent-webui --no-open">Lấy lệnh</button></header>
+      <pre><code>piagent dashboard
+piagent-webui --no-open</code></pre>
+      <p class="command-note">Bí danh: <code>piagent-dashboard</code>, <code>piagent-webui</code>, <code>piagent-explain</code> cũng chạy được như binary riêng.</p>
+    </article>
+    <article class="command-card">
+      <header><span>Giải thích quyết định</span><button class="clip-btn" data-clip="piagent explain &#39;cat .env*&#39;&#10;piagent explain --scope">Lấy lệnh</button></header>
+      <pre><code>piagent explain 'cat .env*'
+piagent explain --scope</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Usage và token</span><button class="clip-btn" data-clip="piagent-usage .&#10;piagent-usage --history . --days 7">Lấy lệnh</button></header>
+      <pre><code>piagent-usage .
+piagent-usage --history . --days 7</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Model và routing</span><button class="clip-btn" data-clip="piagent-models&#10;piagent-model-scope&#10;piagent-route">Lấy lệnh</button></header>
+      <pre><code>piagent-models
+piagent-model-scope
+piagent-route</code></pre>
+    </article>
+    <article class="command-card">
+      <header><span>Subagents và migration</span><button class="clip-btn" data-clip="piagent-subagents --preset safe&#10;piagent-migrate . --apply&#10;piagent-import-instructions">Lấy lệnh</button></header>
+      <pre><code>piagent-subagents --preset safe
+piagent-migrate . --apply
+piagent-import-instructions</code></pre>
     </article>
     <article class="command-card">
       <header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Lấy lệnh</button></header>

package/docs-site/context-engine.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/context-engine" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/context-engine" hreflang="en" lang="en">EN</a>
@@ -184,5 +184,9 @@ piagent-context efficiency</code></pre>
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/architecture.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/architecture" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/architecture" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -181,5 +181,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/benchmark.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/benchmark" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/benchmark" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -314,5 +314,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/commands.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/commands" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/commands" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -206,5 +206,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/context-engine.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/context-engine" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/context-engine" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -160,5 +160,9 @@ piagent-context efficiency</code></pre></article>
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/index.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -111,6 +111,55 @@
   </div>
 </section>
 
+<section class="section">
+  <p class="section-kicker">Production V1 · historical public regression evidence</p>
+  <h2 id="evidence">Measured, not asserted</h2>
+  <p class="section-lead">108 sessions on the same model and thinking level, graded automatically, against an isolated <code>codex-cli</code> surface. This is the production-v1 measurement; it is not a re-measurement of v1.4.0.</p>
+
+  <div class="benchmark-metrics" aria-label="Headline benchmark numbers">
+    <div class="benchmark-metric">
+      <span>Overall</span>
+      <strong>9.92 / 10</strong>
+      <small>Quality, Safety, Reliability all 10/10</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Tasks resolved</span>
+      <strong>54/54</strong>
+      <small>100% on both surfaces</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Fresh tokens</span>
+      <strong>-51.11%</strong>
+      <small>paired geometric mean, 47/54 pair wins</small>
+    </div>
+    <div class="benchmark-metric">
+      <span>Infrastructure</span>
+      <strong>0 retries</strong>
+      <small>108 valid runs</small>
+    </div>
+  </div>
+
+  <div class="benchmark-legend" aria-label="Chart legend">
+    <span><i class="piagent-swatch"></i>Piagent</span>
+    <span><i class="codex-swatch"></i>codex-cli</span>
+  </div>
+
+  <div class="benchmark-usage-chart" aria-label="Median fresh tokens per run: Piagent 7,368, codex-cli 18,476">
+    <div class="benchmark-usage-group">
+      <h3>Fresh tokens, median per run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 39.88%"></i></div><strong>7,368</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>18,476</strong></div>
+    </div>
+    <div class="benchmark-usage-group">
+      <h3>Tool calls, median per run</h3>
+      <div class="benchmark-usage-row"><span>Piagent</span><div class="benchmark-track"><i class="piagent-bar" style="--bar-size: 62.5%"></i></div><strong>5</strong></div>
+      <div class="benchmark-usage-row"><span>codex-cli</span><div class="benchmark-track"><i class="codex-bar" style="--bar-size: 100%"></i></div><strong>8</strong></div>
+    </div>
+  </div>
+
+  <p>The 95% confidence interval on the paired ratio is <strong>0.3809–0.6276</strong>; the upper bound stays below 1.0, so the token-saving claim holds. <a href="/en/benchmark">See the full configuration, every band score, and the raw tables</a>.</p>
+</section>
+
 <section class="section">
   <h2 id="install">Install with two commands</h2>
   <p>Requires Node.js <span class="inline-code">&gt;=22.19.0</span>. Run these commands from the project you want to configure.</p>
@@ -206,5 +255,9 @@ piagent-setup</code></pre>
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>

package/docs-site/en/mcp-approval.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.4.0 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.4.1 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/mcp-approval" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/mcp-approval" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -204,5 +204,9 @@
         <nav data-toc></nav>
       </aside>
     </div>
+    <script>
+      window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
+    </script>
+    <script defer src="/_vercel/insights/script.js"></script>
   </body>
 </html>