@piagent/platform 1.2.12 → 1.2.14

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.14 - 2026-08-03
+
+### Runtime architecture
+
+- Split session lifecycle, input routing, context usage, tool-result filtering,
+  tool activation and task intake out of the guard entrypoint into focused
+  runtime modules while preserving the existing behavior and command surface.
+- Added machine-enforced architecture layers, dependency directions and file
+  size budgets so new runtime code cannot silently grow back into the guard.
+- Extended capability integrity locks to pin every extracted runtime module;
+  the test suite now rejects any runtime file omitted from that trust boundary.
+- Added paired English and Vietnamese maintainer documentation with a language
+  parity gate. Vietnamese docs preserve operational terms such as agent,
+  terminal, workflow, MCP, session, token, model and benchmark.
+
+### Session and migration reliability
+
+- Stopped registering a custom `/name` command so Piagent no longer shadows
+  Pi's native session command. Native rename events continue to update task
+  bindings and Agent Watch records; `/setname` remains a compatibility alias.
+- Hardened legacy task migration so long task identifiers retain a unique hash
+  suffix, the source contract is archived before the v2 write, and path aliases
+  cannot delete a newly written current contract on macOS.
+- Added integration, runtime isolation, migration-collision, architecture and
+  documentation tests for the extracted boundaries and release behavior.
+
+## 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

@@ -1,5 +1,7 @@
 # Pi Agent Platform
 
+[Tiếng Việt](README.vi.md)
+
 Reusable Pi package for project onboarding, profile-based coding workflows, guarded tool usage, multi-agent orchestration, MCP setup, memory policy, and task verification.
 
 Public docs: [piagent.io.vn](https://piagent.io.vn)
@@ -72,7 +74,7 @@ Removal targets what is registered in Pi's settings rather than what the current
 - Workflow launcher via `/workflow` for task, scout, BE-to-FE, review, git, and onboarding work.
 - Runtime onboarding via `/onboard`; `/onboard run` launches the first-read onboarding workflow.
 - Runtime profile selection via `/profile`, plus select-style tech stack setup via `/profile setup` and `/profile tech`.
-- Runtime usage/session controls via `/usage`, `/name`, `/fresh`, plus Pi native `/session`.
+- Runtime usage/session controls via `/usage` and `/fresh`, plus Pi native `/name` and `/session`.
 - Explicit project memory via `/memory` or `/memory-policy` and `piagent_memory_*` tools.
 - Local Context Engine controls via `/context`: incremental code index, hybrid search, token-budgeted packs, bounded current-turn source/test snapshots for automatic tasks, test impact, efficiency telemetry, and semantic compaction. Index storage is owner-only and securely purged when exclusion policy changes; manual packs remain advisory, while current-turn snapshots are freshness-checked and exact edits fail closed on a later mismatch.
 - MCP setup helpers for Context7, Chrome DevTools, GitHub, Playwright, and Figma.
@@ -102,6 +104,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.
 
@@ -244,9 +252,10 @@ Keep provider keys in environment variables, never in committed config. Switchin
 
 ```text
 piagent/
+├─ architecture/                      machine-readable layer and file budgets
 ├─ adapters/                         reusable project profiles
 ├─ catalog/                          deterministic capability index
-├─ docs/                             Vietnamese documentation and operating notes
+├─ docs/                             EN/VI canonical docs plus stable operating guides
 ├─ evals/                            governed evaluation scenarios
 ├─ packs/                            versioned capability manifests and recipes
 ├─ packages/
@@ -279,6 +288,11 @@ This repository intentionally excludes:
 
 ## Documentation
 
+- [Documentation language index](docs/README.md)
+- [Architecture (English)](docs/en/architecture.md)
+- [Architecture (Tiếng Việt)](docs/vi/architecture.md)
+- [Maintainer guide (English)](docs/en/maintainer-guide.md)
+- [Maintainer guide (Tiếng Việt)](docs/vi/maintainer-guide.md)
 - [Public docs site](https://piagent.io.vn)
 - [Static team docs site](docs-site/index.html) — generated from `docs-site/content/`, preview with `npm run site:preview`
 - [Changelog](CHANGELOG.md)
@@ -316,7 +330,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.14` or a reviewed commit.
 
 Ready for:
 

package/README.vi.md

@@ -0,0 +1,90 @@
+# Pi Agent Platform
+
+[English](README.md)
+
+Pi Agent Platform là reusable Pi harness dành cho project onboarding, workflow theo profile, guarded tool usage, MCP, multi-agent orchestration, memory policy, Context Engine và task verification.
+
+Tài liệu public: [piagent.io.vn](https://piagent.io.vn)
+
+## Cài đặt
+
+Yêu cầu Node.js `>=22.19.0`. Chạy từ project cần sử dụng:
+
+```bash
+npm install -g @piagent/platform
+piagent-setup
+```
+
+Sau khi setup:
+
+```bash
+cd /path/to/project
+pi
+```
+
+Trong session Pi đầu tiên của project, chạy `/onboard`. Hằng ngày, dùng `/workflow` để chọn luồng và `/usage` để xem session, model, thinking và token.
+
+## Nguyên tắc vận hành
+
+- Mỗi task dùng một session có tên rõ ràng.
+- Slash command chỉ chạy handler đã đăng ký; agent không phải scout lại command.
+- Prompt hướng dẫn model, còn policy quan trọng được enforce tại runtime.
+- MCP config không chứa token hoặc OAuth credential.
+- Task source-changing cần scope, verify evidence và final gate.
+- Local state nằm trong `.pi/piagent-state/`, có owner-only permission và bounded retention.
+- Project-specific business logic nằm trong project profile hoặc adapter, không đưa vào core.
+
+## Command chính
+
+| Command | Mục đích |
+|---|---|
+| `/workflow` | Chọn workflow task, scout, plan, review, commit, PR hoặc onboarding |
+| `/profile` | Xem hoặc đổi project profile |
+| `/permission` | Đổi permission mode trong session |
+| `/context` | Xem Context Engine, index, retrieval và telemetry |
+| `/usage` | Xem session, model, thinking và context usage |
+| Pi native `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report |
+| `/memory` | Xem hoặc cập nhật explicit project memory |
+| `/onboard` | Khởi tạo project profile và context |
+
+## Architecture
+
+Code được quản lý theo các layer:
+
+1. Composition root đăng ký Pi extension.
+2. Runtime adapter xử lý Pi hook, command, tool và session UI.
+3. Core service xử lý policy, task, context và state.
+4. Integration quản lý MCP, capability và security primitive.
+5. CLI trong `scripts/` chỉ parse argument và gọi use case.
+
+Chạy gate kiến trúc:
+
+```bash
+npm run architecture:check
+```
+
+Đọc chi tiết:
+
+- [Architecture tiếng Việt](docs/vi/architecture.md)
+- [Maintainer guide tiếng Việt](docs/vi/maintainer-guide.md)
+- [Tài liệu tiếng Việt](docs/vi/README.md)
+- [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md)
+- [Command reference tiếng Việt](docs/command-reference-vietnamese.md)
+
+## Verification
+
+```bash
+npm run verify
+```
+
+Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
+
+## Security
+
+Pi Agent Platform là application-level policy layer, không phải OS sandbox. Với untrusted code hoặc adversarial workload, vẫn cần container hoặc VM có filesystem, process, network và credential boundary riêng.
+
+Không commit OAuth token, API key, `auth.json`, session, cache, trust state hoặc dữ liệu nội bộ.
+
+## License
+
+MIT License. Xem [LICENSE](LICENSE).

package/architecture/layers.json

@@ -0,0 +1,117 @@
+{
+  "schemaVersion": 1,
+  "layers": [
+    {
+      "name": "composition",
+      "files": [
+        "packages/piagent-core/extensions/piagent-guard.ts"
+      ]
+    },
+    {
+      "name": "runtime",
+      "roots": [
+        "packages/piagent-core/runtime"
+      ]
+    },
+    {
+      "name": "core",
+      "roots": [
+        "packages/piagent-core/extensions"
+      ]
+    },
+    {
+      "name": "mcp",
+      "roots": [
+        "packages/piagent-core/mcp"
+      ]
+    },
+    {
+      "name": "capabilities",
+      "roots": [
+        "packages/piagent-core/capabilities"
+      ]
+    },
+    {
+      "name": "security",
+      "roots": [
+        "packages/piagent-core/security"
+      ]
+    },
+    {
+      "name": "benchmark",
+      "roots": [
+        "packages/piagent-core/benchmark"
+      ]
+    },
+    {
+      "name": "entrypoints",
+      "roots": [
+        "scripts"
+      ]
+    }
+  ],
+  "allowedDependencies": {
+    "composition": [
+      "runtime",
+      "core",
+      "mcp",
+      "capabilities",
+      "security",
+      "benchmark"
+    ],
+    "runtime": [
+      "runtime",
+      "core",
+      "mcp",
+      "capabilities",
+      "security"
+    ],
+    "core": [
+      "core",
+      "capabilities",
+      "security"
+    ],
+    "mcp": [
+      "mcp",
+      "capabilities",
+      "security"
+    ],
+    "capabilities": [
+      "capabilities",
+      "security"
+    ],
+    "security": [
+      "security"
+    ],
+    "benchmark": [
+      "benchmark"
+    ],
+    "entrypoints": [
+      "entrypoints",
+      "runtime",
+      "core",
+      "mcp",
+      "capabilities",
+      "security",
+      "benchmark"
+    ]
+  },
+  "lineBudgets": {
+    "defaults": {
+      "composition": 500,
+      "runtime": 500,
+      "core": 1000,
+      "mcp": 700,
+      "capabilities": 1200,
+      "security": 400,
+      "benchmark": 1000,
+      "entrypoints": 800
+    },
+    "files": {
+      "packages/piagent-core/extensions/piagent-guard.ts": 8290,
+      "packages/piagent-core/extensions/policy-core.js": 2568,
+      "packages/piagent-core/extensions/context-engine.js": 1342,
+      "scripts/benchmark-runner.mjs": 1432
+    }
+  }
+}

package/docs/README.md

@@ -0,0 +1,23 @@
+# Documentation languages
+
+[English](en/README.md) | [Tiếng Việt](vi/README.md)
+
+Pi Agent Platform keeps canonical maintainer documentation in explicit language directories:
+
+- `docs/en/`: English source.
+- `docs/vi/`: Vietnamese source. Technical keywords such as agent, terminal, workflow, MCP, tool, runtime, context, session, token, model, thinking, and benchmark stay in English.
+- `docs/*.md`: existing operational documents. These remain stable while each maintained topic is moved into an EN/VI pair.
+
+Every normative architecture document must be listed in `docs/languages.json`. The documentation gate requires both language files and reciprocal links in the same change.
+
+## Canonical pairs
+
+| Topic | English | Tiếng Việt |
+|---|---|---|
+| Documentation index | [EN](en/README.md) | [VI](vi/README.md) |
+| Architecture | [EN](en/architecture.md) | [VI](vi/architecture.md) |
+| Maintainer guide | [EN](en/maintainer-guide.md) | [VI](vi/maintainer-guide.md) |
+
+## Existing operating guides
+
+The public static site is Vietnamese and lives under `docs-site/`. Long-form operator documents keep their existing stable paths until they receive a reviewed language pair. Their language must remain explicit in the title or filename during that migration.

package/docs/architecture.md

@@ -1,64 +1,10 @@
-# Kiến trúc Pi Agent Platform
+# Architecture documentation
 
-## Mục tiêu
+- [English architecture](en/architecture.md)
+- [Architecture tiếng Việt](vi/architecture.md)
+- [English maintainer guide](en/maintainer-guide.md)
+- [Maintainer guide tiếng Việt](vi/maintainer-guide.md)
 
-Tách phần agent platform khỏi từng project. Một core dùng chung, nhiều adapter tùy project.
+This compatibility path remains because existing project profiles may include `docs/architecture.md` in `requiredContext`. The canonical language-specific documents above own the detailed architecture.
 
-```text
-User machine
-├─ ~/.pi/agent/
-│  ├─ settings.json              user/global Pi settings
-│  ├─ auth.json                  OAuth token, không commit
-│  └─ mcp.json                   Pi global MCP override
-├─ ~/.config/mcp/mcp.json        shared global MCP config
-└─ <platform-repo>/
-   ├─ package.json               root Pi package manifest
-   ├─ packages/piagent-core   reusable Pi package internals
-   ├─ adapters/*/profile.json    project/domain profiles
-   └─ templates/project          files copied into target projects
-
-Any project
-├─ AGENTS.md                     project instructions
-├─ .mcp.json                     shared MCP config
-└─ .pi/
-   ├─ settings.json              project Pi settings
-   ├─ piagent-profile.json       project adapter
-   ├─ memory/                    project-scoped explicit memory
-   └─ mcp.json                   Pi project MCP override
-```
-
-## Layering
-
-| Layer | Scope | Commit? | Nội dung |
-|---|---|---:|---|
-| OAuth/auth | user machine | Không | `auth.json`, API token, trust state. |
-| Pi global settings | user machine | Không, chỉ template | provider/model, installed packages, telemetry/proxy. |
-| Piagent core | platform repo | Có | extension guard, prompt, skill, policy engine. |
-| Domain pack | platform repo | Có | frontend/backend/data profile chung. |
-| Project adapter | project repo hoặc platform repo | Có | paths, context, verify, MCP capabilities. |
-| Project memory | user/project machine | Không mặc định | `.pi/memory/MEMORY.md` và summary là private-by-default; team chỉ opt-in commit sau review/redaction. |
-
-## Luồng chạy
-
-1. User `cd <project>`.
-2. User chạy `pi`.
-3. Pi đọc global settings và package đã cài.
-4. Nếu project trusted, Pi đọc `.pi/settings.json` và `.pi/piagent-profile.json`.
-5. `piagent-core` extension intercept tool calls.
-6. Agent dùng prompts/skills, MCP registry, context policy, và memory policy.
-7. Memory được đọc/search như advisory context; source hiện tại vẫn là authority.
-8. Trước khi DONE, agent chạy verify theo profile.
-
-## Vì sao không hard-code vào prompt
-
-Prompt chỉ hướng dẫn model. Guard extension có thể block tool call trước khi chạy. Các rule nguy hiểm phải nằm trong policy/extension:
-
-- protected path
-- destructive bash
-- missing verify
-- unsupported MCP capability
-- credential handling
-
-## Project-specific examples
-
-Project đặc thù có thể có backend freeze, structure guide, experience contract, e2e gate. Những thứ này không được đưa vào core; hãy đặt profile riêng trong chính repo project.
+Core rule: Pi Agent Platform is reusable infrastructure. Project-specific business logic belongs in project profiles and adapters. The Pi extension entrypoint composes runtime adapters, core policy/task/context services, MCP/capability integrations, and owner-only local state; dependencies never point back into the entrypoint.

package/docs/command-reference-vietnamese.md

@@ -26,6 +26,7 @@ PiAgent không chiếm các command native đang dùng của Pi. Những command
 |---|---|
 | `/login` | Đăng nhập provider/OAuth. |
 | `/model`, `Ctrl+L` | Chọn model/provider. |
+| `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report. |
 | `/session` | Xem session id/name/token/cost/context hiện tại. |
 | `/resume` | Resume session cũ bằng UI/native flow. |
 | `/compact` | Nén context bằng Pi native compaction. |
@@ -43,7 +44,6 @@ Command ngắn của PiAgent dùng cho workflow và guard local:
 | `/profile` | Profile và tech stack. |
 | `/memory` | Project memory policy. |
 | `/onboard` | Project onboarding/status/setup. |
-| `/name` | Đặt tên session cho Agent Watch/report. |
 | `/fresh` | Tạo session mới cho workflow. |
 
 Riêng MCP governance vẫn giữ `/piagent-mcp` vì `/mcp` đã là command native của Pi.
@@ -109,7 +109,7 @@ Pi Agent dùng ít namespace nhưng mỗi namespace có subcommand/menu rõ:
 
 - `/workflow` là cửa chính cho task/scout/review/git/onboard workflow. Workflow cần agent turn là cố ý và được nói rõ.
 - `/usage` gom live usage, history/report hint, preflight, compact, logs, efficiency.
-- `/name` đặt tên session theo task để Agent Watch/report map đúng việc.
+- Pi native `/name` đặt tên session theo task; Piagent nhận rename event để Agent Watch/report map đúng việc.
 - `/fresh` mở session mới cho `task`, `scout`, hoặc `be-to-fe` khi phiên hiện tại đã nặng.
 - `/context` gom architecture map, code index, search, context pack, test impact, efficiency, preflight và semantic compact.
 - `/permission` gom permission status/read-only/workspace-write/full-access.
@@ -139,7 +139,6 @@ Các command này đến từ package `piagent-core`.
 | `/profile` | Xem/áp profile và chọn tech. | Chạy ngay, không gọi model. |
 | `/profile setup` | Chọn profile + tech bằng option. | Ghi profile/lock/tech manifest. |
 | `/usage` | Xem live usage hoặc report hint. | Menu live/history/preflight/compact/logs/efficiency. |
-| `/name <name>` | Đặt tên session theo task. | Agent Watch/report map đúng task. |
 | `/fresh task|scout|be-to-fe <request>` | Phiên hiện tại đã nặng hoặc muốn tách việc. | Mở session mới có tên và replay workflow prompt gọn. |
 | `/context` | Xem index/search/pack/impact/efficiency/preflight/compact. | Menu context, không gọi model. |
 | `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access. |
@@ -156,7 +155,7 @@ Alias cũ vẫn giữ để không phá thói quen:
 | `/be-to-fe <request>` | `/workflow be-to-fe <request>` |
 | `/commit [message]` | `/workflow commit [message]` |
 | `/pr [title]` | `/workflow pr [title]` |
-| `/setname <name>` | `/name <name>` |
+| `/setname <name>` | Pi native `/name <name>` |
 | `/fresh-task <request>` | `/fresh task <request>` |
 | `/fresh-scout <request>` | `/fresh scout <request>` |
 | `/fresh-be-to-fe <request>` | `/fresh be-to-fe <request>` |
@@ -269,6 +268,7 @@ Các command này thuộc Pi core hoặc package Pi chính. Tên/availability c
 | `Ctrl+P` | Cycle model | Đổi model trong scope nhanh. | Dùng sau khi đã setup `enabledModels`. |
 | `Shift+Ctrl+P` | Cycle model ngược | Quay lại model trước trong scope. | Tiện khi test provider. |
 | `Shift+Tab` | Đổi thinking level | Chọn effort như `medium`, `high`, `xhigh`, `max` nếu model hỗ trợ. | Model không hỗ trợ level nào thì Pi có thể clamp. |
+| `/name <name>` | Đặt tên session | Đối chiếu task trong Agent Watch/report và tìm lại khi resume. | Piagent theo dõi sự kiện rename; `/setname` là alias tương thích. |
 | `/session` | Xem session hiện tại | Cần session id/name/token/cost/context. | Dùng sau `pi --name` hoặc `/name` để kiểm tra tên. |
 | `/resume` | Resume session | Khi tắt nhầm Pi hoặc muốn nối lại work cũ. | Dựa vào session list/id/name của Pi. |
 | `/compact` | Nén context | Khi context usage cao trước task dài. | Chỉ dùng khi cần; đọc lại context quan trọng sau compact. |
@@ -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.14` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.14` | 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.14` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.12` |
+| Registry distribution | `npm:@piagent/platform@1.2.14` |
 | 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.14` | 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.14
 ```
 
 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.14
 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.14` 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.14`.
 
 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.14 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/en/README.md

@@ -0,0 +1,13 @@
+# Pi Agent Platform documentation
+
+[Tiếng Việt](../vi/README.md)
+
+## Start here
+
+- [Architecture](architecture.md): dependency direction, code ownership, runtime flow, and state boundaries.
+- [Maintainer guide](maintainer-guide.md): where new code belongs, file budgets, split queue, and review checklist.
+- [Release and install policy](../release-install-policy.md)
+- [Quality benchmark](../quality-benchmark.md)
+- [Security threat model](../security-threat-model.md)
+
+The English documents in this directory are canonical language peers of the matching files in `docs/vi/`. Code, schemas, command names, and reusable workflow prompts remain English in every language.

package/docs/en/architecture.md

@@ -0,0 +1,81 @@
+# Pi Agent Platform architecture
+
+[Tiếng Việt](../vi/architecture.md)
+
+## Goals
+
+The platform is a reusable Pi harness, not a project-specific application. Its architecture must keep four properties visible in code:
+
+1. Policy decisions are testable without starting Pi.
+2. Pi lifecycle hooks compose features; they do not own every feature implementation.
+3. Local state, MCP, process, and filesystem access stay behind explicit adapters.
+4. Project-specific business rules remain in project profiles and adapters, outside core.
+
+## Dependency direction
+
+```text
+entrypoints/scripts
+        |
+        v
+composition: extensions/piagent-guard.ts
+        |
+        +--------------------+
+        v                    v
+runtime adapters        integrations
+        |                MCP / capabilities
+        v                    |
+core services <-------------+
+policy / task / context / security
+```
+
+Dependencies point downward. Core services never import the Pi composition root or runtime adapters. Runtime adapters may call core services and integrations. Only the composition root registers the complete Pi extension.
+
+The machine-readable rule is `architecture/layers.json`; `npm run architecture:check` enforces it.
+
+## Physical layers
+
+| Layer | Current location | Owns | Must not own |
+|---|---|---|---|
+| Composition | `packages/piagent-core/extensions/piagent-guard.ts` | Wiring, dependency construction, registration order | Feature algorithms, mutable state implementations, large formatters |
+| Runtime adapters | `packages/piagent-core/runtime/` | Pi lifecycle hooks, shared session state, command/tool registration, input routing | Reusable policy decisions |
+| Core services | `packages/piagent-core/extensions/` except the entrypoint | Policy, context, task lifecycle, state services | Pi command menus and UI text |
+| MCP integration | `packages/piagent-core/mcp/` | MCP config layers, readiness, approval, command actions | Task and context policy |
+| Capabilities | `packages/piagent-core/capabilities/` | Profile resolution, pack validation, locks, source roots | Pi session lifecycle |
+| Security foundation | `packages/piagent-core/security/` | Sensitive-data primitives | Workflow behavior |
+| Benchmark | `packages/piagent-core/benchmark/`, `benchmarks/` | Suite validation, scoring, evidence | Runtime enforcement |
+| Entrypoints | `scripts/` | CLI arguments and use-case invocation | Duplicate domain logic |
+| Product assets | `prompts/`, `skills/`, `subagents/`, `adapters/`, `packs/`, `schemas/` | Declarative behavior and contracts | Hidden runtime state |
+
+`extensions/` still contains several historical service modules. The name is legacy; only `piagent-guard.ts` is loaded as a Pi extension. Services move by cohesive feature, with compatibility preserved until the migration is complete.
+
+## Runtime flow
+
+1. Pi loads the single extension entrypoint.
+2. Composition resolves base policy, project profile, capability lock, and local session state.
+3. Runtime hooks normalize input and collect session evidence through one session-scoped state owner.
+4. Core services decide path, shell, MCP, task, context, and final-gate policy.
+5. Runtime adapters register concise tools and slash commands.
+6. Owner-only local state records evidence; prompts remain guidance rather than the enforcement boundary.
+
+## State ownership
+
+| State | Owner | Location | Commit |
+|---|---|---|---:|
+| OAuth and provider auth | Pi/provider | user config | No |
+| Platform install config | Piagent installer | global Pi settings | No |
+| Project profile and lock | Project | `.pi/piagent-profile*.json` | Yes |
+| Task, trace, telemetry, captures | Runtime | `.pi/piagent-state/` | No |
+| Session history | Pi | Pi session store | No |
+| Shared project instructions | Project | `AGENTS.md`, project docs | Yes |
+
+No feature may create a second authoritative representation of the same state. Derived indexes carry a policy digest and must be rebuildable from their source of truth.
+
+## File boundaries
+
+- New runtime modules: at most 500 lines.
+- New core modules: at most 1,000 lines.
+- CLI entrypoints: at most 800 lines; move use cases into package modules.
+- Existing larger files have explicit non-growth budgets in `architecture/layers.json`.
+- Tests mirror the feature path and test public behavior, not private implementation order.
+
+The current split queue and ownership rules are in the [maintainer guide](maintainer-guide.md).