@piagent/platform 1.2.12 → 1.2.13

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.13 - 2026-08-03
+
+### Benchmark evidence
+
+- Published a dedicated static benchmark page with the verified production-v1
+  scores, median usage, paired fresh-token comparison, confidence interval,
+  category coverage and release provenance.
+- Added lightweight CSS charts for score bands, token usage and paired wins;
+  the page has no charting dependency or client-side data fetch and remains
+  readable on desktop and mobile.
+- Added the sanitized v1.2.12 production snapshot to the benchmark guide and
+  README while keeping the raw report private because its root seed can
+  reproduce synthetic secrets.
+- Documented that the full model run measured the release candidate before its
+  metadata bump, and kept the claim scoped to the controlled public suite
+  rather than presenting it as a universal model or repository result.
+
 ## v1.2.12 - 2026-08-03
 
 ### Production benchmark

package/README.md

@@ -102,6 +102,12 @@ Removal targets what is registered in Pi's settings rather than what the current
   reports category/lifecycle/profile bands and 95% token-ratio confidence, and
   reads exact JSONL usage plus privacy-safe tool histograms. Production runs
   retry only zero-usage startup failures and disclose every retry separately.
+- The v1.2.12 production snapshot resolved 54/54 Piagent tasks, scored 10.00 for
+  quality/safety/reliability, 9.58 for workflow, 10.00 for efficiency, and 9.92
+  overall. Against controlled `codex-cli` on the same `gpt-5.6-sol`/`xhigh`
+  matrix, Piagent used 51.11% fewer paired fresh tokens with a 95% ratio interval
+  of `0.3809..0.6276`; see the [benchmark evidence](https://piagent.io.vn/benchmark)
+  and [methodology](docs/quality-benchmark.md).
 - Built-in profiles for frontend, backend, fullstack, BE-readonly/FE-write, data, DevOps, mobile, docs, Python, and Node TypeScript.
 - Versioned capability packs with deterministic catalog, profile resolution, integrity lock, and permission checks.
 
@@ -316,7 +322,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.12` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.2.13` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -468,8 +468,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.2.12` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.12` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.13` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.13` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.12` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.13` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.12` |
+| Registry distribution | `npm:@piagent/platform@1.2.13` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.12` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.13` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.12
+pi install git:github.com/Vt-mmm/piagent@v1.2.13
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.12` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.12`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.13` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.13`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -120,7 +120,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.12 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.13 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.12`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.13`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +282,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.12 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.13 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -971,8 +971,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.2.12` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.12` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.13` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.13` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -1083,7 +1083,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 command -v piagent-install
 ```
 

package/docs/quality-benchmark.md

@@ -206,6 +206,99 @@ Root seed nằm trong `report.json` riêng tư để điều tra/reproduce. Khô
 report production công khai khi chưa loại trường này, vì suite công khai có thể
 dùng seed để tái tạo synthetic secret.
 
+## Kết quả production chuẩn của v1.2.12
+
+Snapshot dưới đây là release evidence đầu tiên của `production-v1`. Candidate
+được chạy từ 22:33 ngày 02/08/2026 đến 00:22 ngày 03/08/2026 theo múi giờ
+Asia/Ho_Chi_Minh, sau đó cùng logic được đóng gói thành `v1.2.12`.
+
+| Thuộc tính | Giá trị |
+|---|---|
+| Run | `production-v1-20260802T153320Z-11f3d0` |
+| Model | `openai-codex/gpt-5.6-sol` cho Piagent, `gpt-5.6-sol` cho `codex-cli` |
+| Thinking | `xhigh` cho cả hai surface |
+| Ma trận | 18 scenario family x 3 repeat x 2 surface = 108 session |
+| Baseline | `codex-cli` controlled mode, home tạm riêng mỗi session |
+| Runtime | Pi `0.82.0`, `codex-cli 0.146.0-alpha.9.2`, Node `24.11.1` |
+| Suite digest | `90a44ac4f5d4ec11772eac00f4f984d78c6962d116581ca29ab6b8760c8f9171` |
+| Hạ tầng | 108 attempt, 0 retry |
+
+### Điểm và kết quả task
+
+| Surface | Resolved | Hidden task grade | Scope | Quality | Safety | Reliability | Workflow | Efficiency | Overall |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| `codex-cli` | 54/54 | 48/48 | 54/54 | 10.00 | 10.00 | 10.00 | n/a | 5.00 baseline | n/a |
+| Piagent | **54/54** | **48/48** | **54/54** | **10.00** | **10.00** | **10.00** | **9.58** | **10.00** | **9.92** |
+
+Piagent đạt `10.00` ở cả sáu category: `backend`, `frontend`, `data`,
+`platform`, `reliability` và `security`. Quality, safety, reliability,
+workflow, category, repeat-count, efficiency-evidence và confidence gate đều
+pass.
+
+Workflow chưa tròn 10 vì mỗi check `session-bound-task`,
+`terminal-completion`, `completed-work-plan` và `single-task-start` hụt ở ba
+run. Các run này vẫn giải đúng task, đúng scope và qua safety gate; report giữ
+gap để Overall không che mất chất lượng vận hành.
+
+### Token và tool usage
+
+Median trên toàn bộ 54 run của mỗi surface:
+
+| Usage | Piagent | `codex-cli` |
+|---|---:|---:|
+| Input đã loại cache | 6,801 | 13,885 |
+| Output | 913 | 2,299 |
+| Cache read | 7,680 | 78,208 |
+| Reasoning, là breakdown của output | 414 | 592 |
+| Fresh token | **7,368** | **18,476** |
+| Tool calls | **5** | **8** |
+| Cost mỗi run | `$0.059141` | `n/a` từ Codex OAuth JSONL |
+
+Biểu đồ median fresh token, lấy `codex-cli` làm thanh 100%:
+
+```text
+Piagent      7,368 | ########             | 39.88% median baseline
+codex-cli   18,476 | #################### | 100.00%
+```
+
+Biểu đồ này chỉ giúp nhìn quy mô median. Efficiency chính thức không chia hai
+median độc lập; runner dùng matched pair theo đúng scenario/repeat:
+
+```text
+Fresh-token pair wins
+Piagent    47 | #################  | 87.04%
+codex-cli   7 | ###                | 12.96%
+Ties         0
+```
+
+- 54/54 cặp có usage và model/thinking tương thích.
+- Piagent thắng 47 cặp, `codex-cli` thắng 7 cặp, không có cặp hòa.
+- Median paired delta là `-7,870` fresh token.
+- Paired geometric mean ratio là `0.4889`, tương ứng giảm `51.11%`.
+- 95% confidence interval của ratio là `0.3809..0.6276`, với 18 scenario
+  family là 18 đơn vị mẫu độc lập.
+- Tổng fresh token của 54 Piagent run là `529,932`; `codex-cli` là `1,006,150`.
+- Tổng chi phí Piagent ghi nhận là `$5.321041`; Codex JSONL không cung cấp cost
+  nên report không suy diễn bảng giá.
+
+Cận trên confidence interval vẫn thấp hơn baseline `1.0`, vì vậy verdict là
+`piagent-more-efficient` và `token-saving claim allowed: yes`.
+
+### Provenance và giới hạn
+
+Full model run diễn ra trước commit bump metadata, nên environment gốc ghi
+platform `v1.2.11`, source working tree dirty. Candidate được test chính là logic
+sau đó phát hành trong `v1.2.12`; 1,253 deterministic test, typecheck, verify,
+audit và CI Linux/macOS được chạy lại sau khi đóng gói. Không chạy lại 108 model
+session chỉ để đổi version metadata.
+
+Raw report không được commit vì giữ root seed có thể tái tạo synthetic secret.
+Snapshot này cố ý chỉ công khai summary, suite digest và provenance không nhạy
+cảm. Đây là benchmark synthetic do maintainer xây dựng, không phải external
+benchmark chứng minh Piagent tốt hơn trên mọi repository/model. Claim triển khai
+toàn công ty vẫn cần đối chiếu held-out suite riêng và task thực tế. Bản trực
+quan của snapshot nằm tại [piagent.io.vn/benchmark](https://piagent.io.vn/benchmark).
+
 ## Bảng điểm
 
 Tất cả band nằm trong khoảng `0-10`:

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.2.12 | Rollout guidance |
+| Surface | Status for v1.2.13 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.12` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.13` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.2.12 (helper package version)
-tag: v1.2.12
+currentRelease: v1.2.13 (helper package version)
+tag: v1.2.13
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.12
+pi install git:github.com/Vt-mmm/piagent@v1.2.13
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -22,7 +22,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.2.12, 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.2.13, 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/team-onboarding.md

@@ -9,7 +9,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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable
 cd /path/to/project
 pi
@@ -43,7 +43,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.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.12
+npm install -g --ignore-scripts @piagent/platform@1.2.13
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs-site/architecture.html

@@ -27,7 +27,7 @@
         <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.13 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -74,6 +74,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>