@piagent/platform 1.40.0 → 1.42.0

package/README.vi.md

@@ -1,193 +1,199 @@
-# Pi Agent Platform
+<p align="center">
+  <a href="https://piagent.io.vn"><img src="https://piagent.io.vn/assets/piagent-logo.svg" alt="Piagent" width="72" height="72"></a>
+</p>
 
-[English](README.md)
+<h1 align="center">Pi Agent Platform</h1>
 
-Pi Agent Platform cung cấp chat trực tiếp, công cụ có kiểm soát quyền, ngữ cảnh dự án và khung main/research/review cho tài khoản công ty.
+<p align="center"><strong>Coding agent cho cả team, kiểm tra từng bước.</strong></p>
 
-Tài liệu public: [piagent.io.vn](https://piagent.io.vn)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@piagent/platform"><img alt="npm" src="https://img.shields.io/npm/v/@piagent/platform?color=c6f432&labelColor=111114"></a>
+  <a href="https://github.com/Vt-mmm/piagent/actions/workflows/verify.yml"><img alt="verify" src="https://github.com/Vt-mmm/piagent/actions/workflows/verify.yml/badge.svg"></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A522.19-111114?labelColor=111114">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-111114?labelColor=111114"></a>
+</p>
+
+<p align="center">
+  <a href="https://piagent.io.vn">Website</a> ·
+  <a href="https://piagent.io.vn/quickstart">Cài đặt</a> ·
+  <a href="https://piagent.io.vn/whats-new">Changelog</a> ·
+  <a href="https://piagent.io.vn/benchmark">Benchmark</a> ·
+  <a href="README.md">English</a>
+</p>
+
+<p align="center">
+  <img src="https://piagent.io.vn/assets/shots/company-run-done.jpg" alt="Dashboard Piagent: một lượt ở chế độ công ty đọc, sửa và chạy test, dòng cuối báo kết quả check và review" width="900">
+</p>
+
+Piagent là một Pi package biến coding agent thành thứ cả team tin dùng được. **Guard** kiểm tra mọi tool call trước khi chạy. Ở chế độ công ty, **Harness** của team chạy check của project và cho một subagent review bản sửa trước khi lượt được báo là xong. Một **dashboard** cho cả Terminal và trình duyệt, dùng tài khoản model của bạn hoặc model của công ty qua Agent Watch và Agent Studio.
+
+## Vì sao chọn Piagent
+
+- **Fail-closed.** File bảo vệ (`.env`, khoá), profile quyền, file quá lớn và sửa trên bản đọc đã cũ bị chặn trước khi chạy, không phải giải thích sau.
+- **Duyệt từng lần.** Push, publish, ghi lên GitHub và lệnh có mạng chờ **Cho phép một lần**. Stage cả loạt như `git add .` cũng hỏi trước.
+- **Lượt có kiểm chứng.** Ở chế độ công ty, mỗi lượt kết thúc bằng một dòng: check đã qua trên code cuối, review có hay không có lỗi chặn.
+- **Chạy được việc dài.** Lỗi tạm thời của nhà cung cấp được hỏi lại, lúc Studio cập nhật thì chờ rồi làm tiếp, một lượt chạy được tới 24 giờ.
+- **Đo được.** Trên [benchmark production](https://piagent.io.vn/benchmark) (v1.6.0, 108 session, cùng model và thinking), Piagent giải 54/54 task so với 48/54 của `codex-cli`, dùng ít hơn 61,43% fresh token (khoảng tin cậy 95%: ít nhất 51,60%).
 
 ## Cài đặt
 
-Yêu cầu Node.js `>=22.19.0`. Chạy từ project cần sử dụng:
+Node.js `>=22.19.0`. Chạy trong project cần dùng:
 
 ```bash
 npm install -g @piagent/platform
 piagent-setup
 ```
 
-Sau khi setup:
+`piagent-setup` cài đúng bản Pi host mà release này pin, cài package, khởi tạo `.pi/`, thêm MCP baseline và subagent, rồi chạy doctor. Bỏ bớt bằng `--no-mcp`, `--no-subagents`, `--no-herdr` hoặc `--global-only`. Muốn dùng [Herdr](https://herdr.dev/docs/install/) thì cài Herdr trước.
+
+**Windows** — một lệnh PowerShell cài WSL2, Ubuntu, Piagent và Agent Watch; chạy lại để cập nhật:
+
+```powershell
+irm https://raw.githubusercontent.com/Vt-mmm/agentwatch/main/windows/setup.ps1 | iex
+```
+
+| Môi trường | Trạng thái |
+|---|---|
+| macOS Apple Silicon | Đã kiểm chứng cho release này |
+| Linux x64 | Đã kiểm chứng trong CI |
+| macOS Intel, Linux ARM64 | Hỗ trợ; chạy `piagent-doctor` và smoke test trước khi rollout rộng |
+| Windows (WSL2) | Chế độ cá nhân và công ty, sandbox bubblewrap, Agent Watch cho Windows ([hướng dẫn](https://piagent.io.vn/windows)) |
+| Windows native | Bản xem trước cho chế độ cá nhân; chưa chạy được `piagent-update` |
+
+## Sử dụng
 
 ```bash
-cd /path/to/project
-pi
+piagent dashboard          # trình duyệt, chế độ cá nhân
+pi                         # Terminal, chế độ cá nhân
+piagent studio --web       # chế độ công ty, sau khi nhập key ở Agent Watch
 ```
 
-Nhập yêu cầu bằng lời thường trong Pi hoặc WebUI. Từ bản 1.9.0 không còn bước `/task` hay `/workflow`, không còn task contract và không còn ngưỡng tiết kiệm token.
+Nói việc bằng lời thường: "sửa lỗi phân trang ở /orders rồi chạy test", "review diff hiện tại, chỉ đọc". Không có task contract hay lệnh workflow phải học. Từ 1.9.0 các launcher `/workflow`, `/task`, `/fresh`, `/onboard` và `/commands` đã bỏ; mở session mới bằng `/new` của Pi.
+
+## Cập nhật
 
-## Agent Watch Auto trên macOS
+Dashboard và Terminal kiểm tra bản mới mỗi giờ, hỏi **Cập nhật ngay** hay **Để sau**. Tự cập nhật:
 
-Admin cấu hình model cho main, khảo sát và review trong Studio. Thành viên nhập URL/key ở Watch, chọn Piagent rồi Import. Mở **Piagent công ty** từ Watch hoặc chạy `piagent studio`; thêm `--web` để mở dashboard. Người dùng chọn mức suy luận; context theo model thực tế. Phiên cá nhân tiếp tục dùng `pi` và chọn model/OAuth riêng.
+```bash
+piagent-update                     # bản mới nhất
+piagent-update --check             # chỉ kiểm tra
+piagent-update --version X.Y.Z     # đúng một bản, mới hơn hay cũ hơn
+```
 
-Key công ty cần loại **Piagent công ty**. Key CLI trực tiếp cũ giữ nguyên; Studio có nút tạo key đi kèm dùng chung hạn mức. Không đổi tài khoản công ty sang cá nhân trong cùng hội thoại.
+Lệnh cài Pi host được pin trước, kiểm tra version trên đĩa rồi mới chạy installer; với `--project` nó migrate project và chạy doctor. Pin cho team, rollback và gỡ cài đặt: [Cập nhật và gỡ](https://piagent.io.vn/update) và [release and install policy](docs/release-install-policy.md).
+
+```bash
+piagent-uninstall           # chỉ báo sẽ gỡ gì
+piagent-uninstall --apply   # gỡ thật
+```
 
-Main có tối đa hai trợ lý chỉ đọc; không sinh nhánh con tiếp. Review gắn với bản chụp patch và báo hết hiệu lực khi code đổi. UI hiển thị token từng trợ lý. Bản macOS managed dùng công cụ cách ly và quyền ngắn hạn theo lượt; chế độ cá nhân vẫn là thực thi trên host.
+Credential, trust, session, todo và memory của project không bao giờ bị xoá.
 
-Bản local này chưa phải bản phát hành có Developer ID. [Trạng thái nghiệm thu](docs/managed-local-acceptance.md) phân biệt test nội bộ, gọi provider thật và phần còn thiếu.
+## Hai chế độ, một dashboard
 
-## Windows
+| | Cá nhân | Công ty |
+|---|---|---|
+| Mở | `pi`, `piagent dashboard` | `piagent studio`, `piagent studio --web` |
+| Model | Tài khoản của bạn, model nào Pi hỗ trợ | Chọn theo vai (main · research · review) trong Agent Studio |
+| Key | Trên máy bạn, do Pi quản lý | Trong Keychain qua Agent Watch; model không bao giờ thấy |
+| Lệnh | Mạng bình thường; push và publish chờ duyệt | Sandbox (Seatbelt / bubblewrap) không mạng; mạng mở theo từng lần duyệt |
+| Kiểm chứng | Bạn yêu cầu | Harness của team chạy check và review mỗi lượt |
 
-Trên Windows, Piagent chạy trong WSL2 (Ubuntu): chế độ công ty với sandbox bubblewrap và Agent Watch cho Windows, và cả chế độ cá nhân. Một lệnh PowerShell cài tất cả. Chạy thẳng trên Windows mới là bản xem trước cho chế độ cá nhân. Cài đặt từng bước: [Windows](docs/vi/windows.md).
+## Có gì bên trong
 
-## Web search và vision
+| Phần | Bạn có |
+|---|---|
+| Guard | Protected và read-only path, profile quyền, kiểm tra bản đọc cũ và file lớn, che secret trong output, hỏi trước việc bên ngoài và việc phá huỷ |
+| Dashboard | Cuộc trò chuyện, cây thư mục, editor, terminal, review từng hunk, Timeline khôi phục và `/undo`, Tài liệu, 13 theme màu, bảng lệnh ⌘K |
+| Harness công ty | Plan · check · review mỗi lượt, câu hỏi hiện từng cái một, team memory với `memory_ask`, cảnh báo sai project, chạy bền cho task dài |
+| Context Engine | Index local tăng dần, tìm kiếm lai, pack theo ngân sách token, compaction theo ngữ nghĩa — `/context` |
+| MCP | `pi-mcp-adapter` với preset đã pin, bốn scope cấu hình, approval gate cho server đến từ repo — `piagent-mcp` |
+| Profile | 11 profile có sẵn (frontend, backend, fullstack, data, DevOps, mobile, docs…) với protected path và verify command — `/profile` |
+| Báo cáo | `fe-change-report`: ảnh trước/sau khung đỏ đánh số, check và E2E, xem trong Tài liệu |
 
-Web research và đọc ảnh là hai capability tách biệt. Tích hợp `pi-web-access`
-được pin sẽ ưu tiên route `openai-codex` khi Pi đã xác thực và giữ fallback search
-tự động; credential không được đưa vào project hoặc browser state. Ảnh được gửi
-dưới dạng native image input cho model của session, không qua OCR service riêng
-do Piagent vận hành. Dashboard hiển thị đúng route tại **Cài đặt → Nhà cung cấp &
-model**: `Codex Web Search` khi route đó sẵn sàng, và `Codex Vision` chỉ khi model
-Codex hiện tại công bố hỗ trợ image input.
+<details>
+<summary><strong>Permission profile</strong></summary>
 
-## Workspace tài liệu trên WebUI
+| Profile | Dùng khi | Guard làm gì |
+|---|---|---|
+| `read-only` | Khảo sát, audit, review | Cho `read`, `grep`, `find`, `ls` và tool state của piagent; chặn shell, sửa file và tool lạ. |
+| `workspace-write` | Code bình thường | Mặc định. Kiểm tra protected path, read-only path, shell và capability; hỏi trước việc phá huỷ hay bên ngoài. |
+| `trusted-full-access` | Tự động hoá tin cậy trên máy | Tự chủ hơn, vẫn giữ protected path, che secret, toàn vẹn capability lock và xác nhận việc phá huỷ/bên ngoài. |
+| `bypass` | Bạn chấp nhận mọi rủi ro | Không gate nào hỏi hay chặn. Output vẫn được che secret và mỗi lượt vẫn có checkpoint `/undo`. Bỏ khỏi `permissionProfiles.allowedModes` để cấm; ở chế độ công ty admin Studio tắt được (`bypass_mode`). |
 
-Session Hub cho phép đính kèm ảnh hoặc tài liệu do người dùng chọn vào cuộc trò
-chuyện mới hay session đang mở. File Markdown, text, PDF và DOCX được trích xuất
-cục bộ với giới hạn rõ ràng; chat chỉ giữ card file gọn, còn workspace **Tài
-liệu** hiển thị preview dễ đọc mà không tạo model turn. File vượt giới hạn gửi
-trực tiếp vẫn nằm trong workspace của project thay vì bị nhét vào prompt. Runtime
-tiếp tục áp protected path, redaction, session binding và attachment ref dùng một
-lần.
+Trong Pi dùng `/permission` (menu), `/permission status`, `/permission read-only`, `/permission workspace-write`, `/permission full-access [việc]` hoặc `/permission bypass`. Cho một lần chạy: `PIAGENT_PERMISSION_PROFILE=…` hoặc `piagent-auto --read-only|--workspace-write|--full-access|--bypass`.
 
-Màn hình New chat gửi đúng nội dung người dùng nhập; WebUI không còn bộ chọn
-workflow. Trong **Cài đặt → Điều khiển project**, operator có thể xem
-runtime/usage, profile, Context Engine, memory và MCP governance mà không cần nhớ
-slash command. WebUI gửi đúng command vào Pi runtime; thao tác read-only được
-kiểm tra là 0 model token, còn thao tác ghi hoặc semantic compact bắt buộc xác
-nhận rõ ràng. Muốn onboard project, hãy nhờ agent trong chat đọc project (chỉ
-đọc) và ghi lại context.
+</details>
 
-## Command chính
+<details>
+<summary><strong>Lệnh trong session</strong></summary>
 
-Công việc được yêu cầu bằng lời thường; các command dưới đây là thiết lập và màn
-hình chỉ đọc, không command nào mở lượt model.
+Đây là cài đặt và màn xem chỉ đọc; không lệnh nào mở lượt model. Giải thích từng lệnh ở [command reference](docs/command-reference-vietnamese.md).
 
-| Command | Mục đích |
+| Lệnh | Dùng để |
 |---|---|
-| `/profile` | Xem hoặc đổi project profile; `/profile setup` chọn tech cho từng vai trò |
-| `/permission` | Đổi permission mode trong session; `/permission bypass` (hoặc `piagent-auto --bypass`) tắt mọi cổng kiểm soát của Piagent như bypass của Codex, vẫn che secret trong output và giữ `/undo`; cuộc trò chuyện company dùng `/bypass on` khi admin Studio để Bypass bật trong Harness |
-| `/context` | Xem Context Engine, index, retrieval và telemetry |
-| `/usage` | Xem session, model, thinking và context usage |
-| `/piagent-inspector` | Mở menu read-only để xem task diff, command fail/block, safety warning và context budget; panel bốn dòng tự hiện sát footer native, `toggle` để ẩn trong session |
-| 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 |
-| `/piagent-mcp` | Xem và quản lý MCP server, scope và phê duyệt |
-| `/piagent-status` | Xem profile, guard, runtime và trạng thái model đã xác thực |
-
-Các command workflow (`/workflow`, `/task`, `/scout`, `/fresh`, `/onboard`,
-`/commands`, `/model-options`) đã bỏ từ bản 1.9.0. Hãy nói điều mình cần, ví dụ
-"scout luồng thanh toán, chỉ đọc, không sửa", "review diff hiện tại", "commit hai
-file này". Session đã nặng thì mở session mới bằng `/new` của Pi. `git push`,
-thao tác ghi lên GitHub và publish đều hỏi xác nhận trước.
-
-## 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, context và state (bản ghi task cũ chỉ còn để đọc lịch sử).
-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:
+| `/profile` | Xem hoặc áp profile. `/profile setup`, `/profile tech`, `/profile auto` chọn tech cho từng vai. |
+| `/permission` | Xem hoặc đổi permission profile của session. |
+| `/context` | Index, tìm kiếm, pack, test impact và compaction của Context Engine. |
+| `/usage` | Usage của session, model, thinking và context; `/usage logs` xem output tool đã thu gọn. |
+| `/memory` | Memory của project. |
+| `/piagent-mcp` | MCP server, scope và approval. |
+| `/piagent-status` | Trạng thái profile, guard, runtime và model đã đăng nhập. |
+| `/piagent-inspector` | Diff, lệnh và lỗi, cảnh báo an toàn và ngân sách context trong một menu chỉ đọc. |
+| `/piagent-orchestration` | Chế độ helper, giới hạn và lý do dispatch. |
 
-```bash
-npm run architecture:check
-```
+Git vẫn là capability: nói "commit hai file này" hay "mở PR" (prompt `/commit` và `/pr` cho cùng flow). Chọn model bằng `/model` hoặc `Ctrl+L` của Pi; xem [Model options](docs/model-options.md).
 
-Đọ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)
-
-## Cấu trúc repository
-
-```text
-piagent/
-├─ architecture/                      quy tắc layer và giới hạn file cho máy kiểm tra
-├─ adapters/                          profile project tái sử dụng
-├─ catalog/                           capability index xác định
-├─ docs/                              tài liệu chuẩn EN/VI và hướng dẫn vận hành ổn định
-├─ evals/                             kịch bản đánh giá có governance
-├─ packs/                             capability manifest và recipe có version
-├─ packages/
-│  ├─ piagent-core/                   Pi package: extension, runtime, skill, managed harness
-│  └─ piagent-webui/                  dashboard: contract, client, server, gateway, ownership
-├─ schemas/                           JSON schema
-├─ scripts/                           setup, doctor và helper kiểm tra
-└─ templates/                         template project/global
-```
+</details>
 
-`piagent-core` là Pi extension và có thể chạy headless độc lập. `piagent-webui`
-là giao diện `piagent dashboard`, nằm trên một dependency spine riêng: WebUI đọc
-platform nhưng platform không phụ thuộc ngược vào WebUI, nên runtime vẫn hoạt động
-khi không mở dashboard. Cả hai sơ đồ layer đều được kiểm tra bằng
-`npm run architecture:check`; xem [Architecture](docs/vi/architecture.md).
+<details>
+<summary><strong>Subagent và MCP</strong></summary>
 
-## Adaptive model routing
+Model chính lo suy luận, sửa code và kiểm chứng. Khi bật helper, nó được giao tối đa hai helper chỉ đọc (khảo sát, hoặc review bản sửa); helper không sửa code và không mở helper khác. `piagent-setup` cài runtime `pi-subagents` với preset giới hạn; `/subagents-doctor` kiểm tra sức khoẻ. Chi tiết: [Subagent orchestration capabilities](docs/subagent-orchestration-capabilities.md), [auto-delegation](docs/auto-delegation-policy.md), [subagents and multi-agent](docs/subagents-and-multiagent.md).
 
-Adaptive model routing cho fresh task dùng `piagent-route --prompt "<task>" --json`.
-Chỉ `--execute --yes` mới mở provider-backed Pi process; `/model`/CLI pin luôn
-được giữ và extension không đổi model giữa conversation.
+`piagent-setup` cài `pi-mcp-adapter` và preset `core` (Context7, Chrome DevTools, GitHub); `popular` thêm Playwright và Figma. Bước này chỉ ghi định nghĩa server, server kết nối khi cần. Giữ key của nhà cung cấp trong biến môi trường. Tìm kiếm web qua add-on `pi-web-access` đã pin. Xem [MCP and tools](docs/mcp-and-tools.md).
 
-## Verification
+</details>
 
-```bash
-npm run verify
-```
+<details>
+<summary><strong>Mô hình bảo mật</strong></summary>
 
-Gate riêng cho parity WebUI/Terminal (không gọi provider) và suite logic sâu dùng
-baseline Luna/medium so với `codex-cli`:
+Guard là lớp chống sự cố ở tầng ứng dụng, không phải OS sandbox. Nó chặn truy cập dạng đường dẫn tới protected path trên tool có sẵn, tool tự viết và MCP (object lồng nhau, `file://`, percent-encoding, không phân biệt hoa thường, symlink thoát ra ngoài), tách operand của shell để chặn `bash` truy cập trực tiếp, hỏi trước khi shell ghi ra bên ngoài, và che dữ liệu nhạy cảm trong output. [Redaction benchmark](docs/security-redaction-benchmark.md) bắt 52/52 mẫu secret theo ngữ cảnh, 0/30 văn bản thường bị che nhầm; đây là cổng nội bộ, không phải audit độc lập.
 
-```bash
-npm run benchmark:webui-parity
-npm run benchmark:deep -- --dry-run
-npm run benchmark:deep
-```
+Với code hoặc prompt không tin cậy, chạy Pi trong container hoặc VM có ranh giới filesystem, process, mạng và credential. Threat model: [docs/security-threat-model.md](docs/security-threat-model.md). Báo lỗ hổng riêng tư theo [SECURITY.md](SECURITY.md).
+
+</details>
+
+## Bằng chứng
 
-`deep-logic-v1` có 7 scenario difficulty `large`, khóa Piagent/`codex-cli` ở
-Luna/medium và chạy 3 repeat trên 2 surface (42 model session). Suite phủ event
-reconciliation, fair dependency scheduling, layered policy, graph-aware context,
-resumable stream, transactional config và temporal usage billing chính xác; claim chỉ được phép khi đủ full suite,
-token và duration gate, đồng thời không có retry. Retry diagnostic vẫn được ghi
-rõ nhưng làm release gate fail. `--dry-run` chỉ validate kế hoạch, không dùng
-quota.
+| Đo gì | Kết quả | Nguồn |
+|---|---|---|
+| Task giải được, production-v1 (v1.6.0, GPT-5.6 Luna Medium) | Piagent 54/54 · `codex-cli` 48/54 | [benchmark](https://piagent.io.vn/benchmark) |
+| Fresh token, family fixed-workload chính | tỷ lệ `0.3857` (−61,43%), CI 95% `0.3073..0.4840` | [phương pháp](docs/quality-benchmark.md) |
+| Đếm usage | 108/108 session chính xác, không retry | cùng lần chạy |
+| Che secret | 52/52 mẫu theo ngữ cảnh, 0/30 báo nhầm | [redaction benchmark](docs/security-redaction-benchmark.md) |
+| Nhịp phát hành | mọi bản trong [CHANGELOG.md](CHANGELOG.md) | [trang changelog](https://piagent.io.vn/whats-new) |
 
-Run production-v1 public của `v1.6.0`,
-`production-v1-20260824T040017Z-05b7cf`, được đo trên đúng commit
-`3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` bằng GPT-5.6 Luna Medium với
-108 session. Piagent hoàn thành 54/54 task, so với 48/54 của `codex-cli`. Tỷ lệ
-fresh token theo family fixed-workload chính là `0,3857` (thấp hơn 61,43%), với
-khoảng tin cậy 95% `0,3073..0,4840`; cận trên cho phép phát biểu thận trọng rằng
-Piagent dùng ít hơn ít nhất 51,60% fresh token trên đúng workload đã khai báo
-trước và đúng release này. Usage của cả 108 session đều exact và không có retry.
-Xem [bằng chứng benchmark](https://piagent.io.vn/benchmark) và
-[phương pháp](docs/quality-benchmark.md).
+Benchmark là bộ bài tổng hợp do maintainer dựng, đo ở v1.6.0 và chưa đo lại cho các bản sau; không có kết luận nào về thời gian hay chi phí. Tự chạy bằng `piagent-benchmark --production --dry-run`, hoặc bản nhanh `core-v1` bằng `piagent-benchmark --dry-run`.
 
-Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
+## Đóng góp
+
+```bash
+npm ci
+npm run verify
+```
 
-Bản phát hành hiện tại là `v1.40.0`. Với team hoặc production, hãy pin tag này
-hoặc một commit đã review thay vì dựa vào nguồn package không cố định.
+`npm run verify` chạy typecheck, test, capability catalog, doctor và các check kiến trúc, câu chữ, docs site. Docs site và `CHANGELOG.md` được sinh tự động: sửa `docs-site/content/` và `docs-site/releases.json`, rồi chạy `node scripts/build-docs-site.mjs`. Quy trình: [CONTRIBUTING.md](CONTRIBUTING.md). Bố cục và luật layer: [Kiến trúc](docs/vi/architecture.md).
 
-## Security
+Repo này không bao giờ chứa OAuth token, `auth.json`, file `.env`, key MCP hay nhà cung cấp, session của Pi, dữ liệu project hay đường dẫn trên máy.
 
-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.
+## Tài liệu
 
-Không commit OAuth token, API key, `auth.json`, session, cache, trust state hoặc dữ liệu nội bộ.
+- **Bắt đầu:** [Website](https://piagent.io.vn) · [Cài đặt](https://piagent.io.vn/quickstart) · [Hệ sinh thái](https://piagent.io.vn/ecosystem) · [Quickstart tiếng Việt](docs/quickstart-vietnamese.md) · [Team onboarding](docs/team-onboarding.md)
+- **Sử dụng:** [Command reference](docs/command-reference-vietnamese.md) · [Workflow recipes](docs/workflow-recipes.md) · [Model options](docs/model-options.md) · [OAuth providers](docs/oauth-providers.md) · [Context Engine](docs/context-engine.md) · [Memory policy](docs/memory-policy.md)
+- **Vận hành:** [Operator manual](docs/operator-manual-vietnamese.md) · [Release and install policy](docs/release-install-policy.md) · [Publishing for teams](docs/publishing-for-teams.md) · [Usage observability](docs/usage-observability.md)
+- **Bên trong:** [Kiến trúc](docs/vi/architecture.md) · [Runtime policy design](docs/runtime-policy-design.md) · [Security threat model](docs/security-threat-model.md) · [Quality benchmark](docs/quality-benchmark.md) · [Mọi tài liệu](docs/README.md)
 
-## License
+## Giấy phép
 
-MIT License. Xem [LICENSE](LICENSE).
+MIT. Xem [LICENSE](LICENSE).

package/architecture/layers.json

@@ -97,6 +97,12 @@
         "packages/piagent-webui"
       ]
     },
+    {
+      "name": "skills",
+      "roots": [
+        "packages/piagent-core/skills"
+      ]
+    },
     {
       "name": "entrypoints",
       "roots": [
@@ -140,6 +146,9 @@
     "benchmark": [
       "benchmark"
     ],
+    "skills": [
+      "skills"
+    ],
     "webui-contracts": [
       "webui-contracts"
     ],
@@ -219,6 +228,7 @@
       "capabilities": 1200,
       "security": 400,
       "benchmark": 1000,
+      "skills": 500,
       "webui-contracts": 2000,
       "webui-client": 500,
       "webui-server": 500,

package/docs/command-reference-vietnamese.md

@@ -477,8 +477,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@1.3.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.40.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.40.0` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.42.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.42.0` | 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

@@ -15,9 +15,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.40.0` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.42.0` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.40.0` |
+| Registry distribution | `npm:@piagent/platform@1.42.0` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -54,7 +54,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.40.0
+pi install git:github.com/Vt-mmm/piagent@v1.42.0
 ```
 
 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.
@@ -66,12 +66,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@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.40.0` 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.40.0`.
+`pi install git:github.com/Vt-mmm/piagent@v1.42.0` 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.42.0`.
 
 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).
 
@@ -118,7 +118,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.40.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.42.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/en/architecture.md

@@ -44,6 +44,7 @@ The machine-readable rule is `architecture/layers.json`; `npm run architecture:c
 | 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 |
+| Skills | `packages/piagent-core/skills/` | Skill instructions and the helper scripts a skill runs in the member's project | Runtime enforcement, imports from other layers |
 | WebUI contracts | `packages/piagent-webui/contracts/` | Wire types shared by browser and server | Any runtime behavior; it depends on nothing |
 | WebUI shared | `packages/piagent-webui/shared/` | Dependency-free deterministic helpers shared by browser, server, and gateway | Browser state, transport, filesystem access, or runtime policy |
 | WebUI client | `packages/piagent-webui/client/` | Browser views, view models, UI preferences | Server state, filesystem, Pi APIs |

package/docs/languages.json

@@ -21,8 +21,8 @@
       "en": "README.md",
       "vi": "README.vi.md",
       "consistentAt": {
-        "en": "357a2e81d0fb805ad710fe4ad3afb757d38cc0b9",
-        "vi": "f1ab56e2ec3b8e9fdadab8e1fc48e87d3d9c08ce"
+        "en": "ad3f53b99174fa8a622daf5fd12b913fbf7c39d5",
+        "vi": "8226fcd96616a25cad27922a358b2b2adf1de735"
       }
     },
     {
@@ -39,8 +39,8 @@
       "en": "docs/en/architecture.md",
       "vi": "docs/vi/architecture.md",
       "consistentAt": {
-        "en": "932086b9d8bf0ccc370d898f945a347b0442e295",
-        "vi": "2023f60b40e2fd6025985e84967eec412b2636d8"
+        "en": "d4615bd0f084a71c2f1a8863c36b8ffb3e407932",
+        "vi": "72a9e0de0ccf28e97e7ece548287c0201585910b"
       }
     },
     {

package/docs/operator-manual-vietnamese.md

@@ -19,12 +19,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@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 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.40.0`. 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.42.0`. 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:
 
@@ -100,7 +100,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -285,7 +285,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.40.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.42.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -999,8 +999,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.40.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.40.0` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.42.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.42.0` | 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. |
@@ -1096,7 +1096,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.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -41,7 +41,9 @@ pi install /path/to/piagent
 
 ## Versioning
 
+- `1.42.0`: dashboard thiết kế lại (một thang thiết kế, 13 theme tô tới mọi khung, header 52px, trang tạo mới có việc mẫu); tin cũ tự tải khi cuộn lên và giữ nguyên chỗ đang đọc, lịch sử hiện đúng định dạng ngay từ đầu, cửa sổ lịch sử 1.000 mục có nút về tin mới nhất; mỗi lượt đang chạy chỉ một hiệu ứng chạy; website và README viết lại; ghi chú phát hành có một nguồn `docs-site/releases.json` sinh ra `CHANGELOG.md`.
 - `1.39.0`: cuộc trò chuyện công ty gửi Studio danh sách repository (`POST /studio/v1/managed/workspace`, chỉ khi Studio có `managed.workspace.v1`, Agent Studio 0.39.0); repo thuộc team khác hoặc ngoài danh sách repo của team hiện một dòng cho member (`agent-watch-project`, `managedProjectWarning`), không chặn; dashboard lưu ngôn ngữ và theme ở Gateway (`piagent-gateway/ui-preferences.json`) nên giữ sau khi khởi động lại.
+- `1.41.0`: skill `fe-change-report` (chụp ảnh cũ/mới headless, khung đỏ đánh số, `report.html` không script); dashboard vẽ `reports/fe-change/<slug>/report.json` trong Tài liệu, ảnh qua `GET /api/v1/documents/<ref>/assets/<name>` (`document-asset-v1`), chỉ PNG trong `shots/` cạnh `report.json`.
 - `1.40.0`: thư mục không có remote đọc được được báo cho Studio như project local (`local/git/<root commit>` hoặc `local/dir/<hash máy + đường dẫn>`, kèm tên thư mục, chỉ khi Studio có `managed.workspace.v2`, Agent Studio 0.40.0); mỗi run báo một lần; member thấy dòng cảnh báo cho mọi loại (`other_team`, `unlisted`, `unregistered`, `no_repository`; `managedProjectWarning` có thêm `name`).
 - `1.38.2`: khung Tệp là cây thư mục như VS Code; theme màu (Piagent, Dracula, One Dark, Monokai, Nord, Tokyo Night, Catppuccin Mocha, Gruvbox, Solarized, GitHub) cho giao diện, editor và terminal, lưu trên trình duyệt (`piagent-webui-theme`); editor và terminal ghim dưới header khi hội thoại cuộn, có thanh chia độ rộng.
 - `1.38.1`: nội dung như 1.38.0; 1.38.0 có tag nhưng không được publish vì hai test của bước kiểm tra phát hành (fixture Linux của terminal công ty, thời gian chờ thẻ duyệt).

package/docs/release-install-policy.md

@@ -153,7 +153,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@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -179,7 +179,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.40.0
+pi install git:github.com/Vt-mmm/piagent@v1.42.0
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -389,7 +389,7 @@ gh run rerun <run-id> --failed
 
 Re-running the workflow from a branch instead skips publishing, because the publish step requires a tag ref.
 
-1. Update package versions, `CHANGELOG.md`, install examples, and docs metadata on a release-candidate branch.
+1. Update package versions, install examples, and docs metadata on a release-candidate branch. Add the release to the top of `docs-site/releases.json` (title, one-sentence summary, items tagged `new`, `improved`, `fixed`, `security` or `breaking`, in English and Vietnamese, plus any Studio or Agent Watch it `requires`), then run `node scripts/build-docs-site.mjs`: it regenerates `CHANGELOG.md`, the Changelog page in both languages and the landing page's latest releases. Do not edit `CHANGELOG.md` by hand; `build-docs-site.mjs --check` fails when it drifts.
 2. Verify the exact release-candidate source:
 
    ```bash

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@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 piagent-install --stable
 cd /path/to/project
 pi
@@ -45,7 +45,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@1.3.0
-npm install -g --ignore-scripts @piagent/platform@1.40.0
+npm install -g --ignore-scripts @piagent/platform@1.42.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```

package/docs/vi/architecture.md

@@ -44,6 +44,7 @@ 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 |
+| Skills | `packages/piagent-core/skills/` | Hướng dẫn skill và script phụ trợ skill chạy trong project của member | Thực thi runtime, import từ layer khác |
 | 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 shared | `packages/piagent-webui/shared/` | Helper xác định, không có dependency, dùng chung cho browser, server và gateway | Browser state, transport, truy cập filesystem hoặc runtime policy |
 | WebUI client | `packages/piagent-webui/client/` | View trên browser, view model, UI preference | Server state, filesystem, Pi API |