@piagent/platform 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.6 - 2026-07-31
+
+### Added
+
+- Added Pi Context Engine v2: a local incremental SQLite FTS5 index with symbol and import extraction, hybrid Reciprocal Rank Fusion and personalized PageRank retrieval, hard-budget context packs, reverse-import test impact, and the `piagent-context` terminal command.
+
+- Added Agent Watch compatible context telemetry keyed by Pi session ID and session name. It records model/thinking metadata, active tool counts, usage, retrieval confidence, context-pack utilization, duplicate reads/output, and transparent context-waste metrics without duplicating raw prompts or tool output.
+
+### Changed
+
+- Piagent now starts with a one-tool loader and activates governance, policy, code retrieval, knowledge, onboarding, and usage groups by task shape. Tiny tasks expose 11 of 30 Piagent tools and ordinary tasks expose 15, while runtime guards remain active regardless of the visible tool schema.
+
+- Task and scout workflows are risk-adaptive. Unfamiliar work receives one bounded Context Engine pack, low-confidence retrieval permits at most one read-only finder pass, repeated read/search results collapse to a delta marker, and session compaction preserves task state instead of raw logs.
+
+- Quality benchmarks now record fresh input, output and cache-read tokens, first-correct-edit time, rework count, and a context-efficiency snapshot so token savings are compared against acceptance and verification quality.
+
+### Fixed
+
+- Release installation now removes an older local `@piagent/platform` registration as well as older Git registrations before installing the pinned release, preventing the local checkout and released package from loading together.
+
+## v1.2.5 - 2026-07-30
+
+### Fixed
+
+- `piagent-update` now accepts npm 12's singleton-array `npm view --json` output when resolving the target helper version and its pinned Pi host peer dependency. Empty or multi-entry metadata still fails closed, so the updater never guesses which release or host to install.
+
 ## v1.2.4 - 2026-07-30
 
 ### Changed

package/README.md

@@ -74,7 +74,7 @@ Removal targets what is registered in Pi's settings rather than what the current
 - 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`.
 - Explicit project memory via `/memory` or `/memory-policy` and `piagent_memory_*` tools.
-- Compact project context controls via `/context` or `/context index` and `piagent_context_index_*` tools. This is an advisory navigation graph, not a security boundary or source of truth.
+- Local Context Engine controls via `/context`: incremental code index, hybrid search, token-budgeted packs, test impact, efficiency telemetry, and semantic compaction. Results remain advisory, not a security boundary or source of truth.
 - MCP setup helpers for Context7, Chrome DevTools, GitHub, Playwright, and Figma.
 - Subagent setup helpers for read-only scouting, planning, implementation, review, and risk challenge.
 - Chat image-path intake: paste a local screenshot path into the Pi chat box and the guard attaches it as `[image1]` before the model sees the prompt.
@@ -261,6 +261,7 @@ This repository intentionally excludes:
 - [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md)
 - [Quickstart tiếng Việt](docs/quickstart-vietnamese.md)
 - [Command reference tiếng Việt](docs/command-reference-vietnamese.md)
+- [Pi Context Engine](docs/context-engine.md)
 - [Team onboarding](docs/team-onboarding.md)
 - [Project onboarding](docs/project-onboarding.md)
 - [Workflow recipes](docs/workflow-recipes.md)
@@ -290,7 +291,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.4` 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.6` or a reviewed commit.
 
 Ready for:
 

package/catalog/capabilities.json

@@ -26,8 +26,8 @@
           "path": "evals/scenarios/capability-resolution.json"
         },
         {
-          "byteSize": 6146,
-          "digest": "sha256:a7a975b99ed2f45881d110582fb6990c500f7e081f865230bf9e4ae242cdd81e",
+          "byteSize": 6201,
+          "digest": "sha256:35398d414c6fd57f63c81990881410ad4286074c2c63fbf53a808b6cfb27b343",
           "id": "base-policy",
           "kind": "policies",
           "path": "packages/piagent-core/policies/base-policy.json"
@@ -61,8 +61,8 @@
           "path": "packages/piagent-core/prompts/review.md"
         },
         {
-          "byteSize": 5073,
-          "digest": "sha256:1dd1339b1e0d8e5882595a38da1781e5b8f59d96afdf4dcdc45c6a77ad7ccfe5",
+          "byteSize": 3452,
+          "digest": "sha256:d06f189c7cf6484cc60d79c200e85ff60f543651264b9233cb23686145cc35d8",
           "id": "task",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/task.md"

package/docs/command-reference-vietnamese.md

@@ -37,8 +37,8 @@ Command ngắn của PiAgent dùng cho workflow và guard local:
 |---|---|
 | `/commands` | Menu/help command, không gọi model. |
 | `/workflow` | Launcher task/scout/plan/review/git/onboard. |
-| `/usage` | Usage live/history/preflight/compact/logs. |
-| `/context` | Context index/search/preflight/compact. |
+| `/usage` | Usage live/history/preflight/compact/logs/efficiency. |
+| `/context` | Smart index/rebuild/search/pack/impact/efficiency/preflight/compact. |
 | `/permission` | Permission mode của session. |
 | `/profile` | Profile và tech stack. |
 | `/memory` | Project memory policy. |
@@ -65,6 +65,7 @@ Trong Pi:
 /commands
 /onboard
 /context index
+/context rebuild
 /memory
 ```
 
@@ -107,10 +108,10 @@ Nếu task còn mơ hồ:
 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.
+- `/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.
 - `/fresh` mở session mới cho `task`, `scout`, hoặc `be-to-fe` khi phiên hiện tại đã nặng.
-- `/context` gom context index, search, preflight, compact.
+- `/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.
 - `/profile` là namespace duy nhất cho profile và tech stack.
 - `/commands` là runtime help/menu, không còn bắt agent đọc docs để giải thích.
@@ -137,10 +138,10 @@ Các command này đến từ package `piagent-core`.
 | `/onboard` | First-run setup/status. | Mở menu onboarding: status, run, profile, setup. |
 | `/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. |
+| `/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 context index/search/preflight/compact. | Menu context, không gọi model. |
+| `/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. |
 | `/memory` hoặc `/memory-policy` | Xem memory policy. | Chạy ngay, không gọi model. |
 | `/model-options` | Xem hướng dẫn model/thinking. | Chạy ngay; chọn model vẫn dùng `/model` hoặc `Ctrl+L`. |
@@ -464,8 +465,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.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.4` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.6` | 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/context-engine.md

@@ -0,0 +1,177 @@
+# Pi Context Engine
+
+## Mục tiêu
+
+Pi Context Engine giảm token bằng cách giảm context nhiễu, không đổi model chính
+và không hạ thinking level. Runtime chọn đúng tool, file, symbol và test trước khi
+model bắt đầu scout rộng.
+
+```text
+task
+  -> deterministic task signals
+  -> dynamic tool groups
+  -> explicit path + FTS5 + symbol/import graph + git/test signals
+  -> Reciprocal Rank Fusion + personalized PageRank
+  -> token-budgeted context pack
+  -> selected parent model
+  -> delta tool results + semantic compaction
+  -> local telemetry for Agent Watch
+```
+
+## P0: runtime context controls
+
+- Piagent tools được chia thành `governance`, `policy`, `retrieval`,
+  `knowledge`, `onboarding`, và `usage`. Code retrieval không tự kéo theo
+  memory, document intake, source checkout hoặc orchestration.
+- Session bắt đầu với loader nhỏ. Input hook bật nhóm cần cho task trước khi
+  system prompt được tạo.
+- `piagent_tools` chỉ mở thêm nhóm được yêu cầu; runtime guard vẫn chạy kể cả
+  khi policy tool không hiện với model.
+- Tool order cố định để giữ prompt prefix ổn định cho provider có prompt cache.
+- Read/grep/find/ls lặp lại với cùng input và cùng output trả delta marker thay
+  vì chèn lại toàn bộ kết quả.
+- Telemetry không lưu prompt hoặc tool output thô. Nó lưu hash, kích thước, tool,
+  model, thinking, active-tool count, usage, retrieval confidence và đường dẫn
+  tương đối đã được guard redaction.
+
+Rollback flags:
+
+```bash
+PIAGENT_DYNAMIC_TOOLS=off pi
+PIAGENT_AUTO_CONTEXT=off pi
+PIAGENT_CONTEXT_TELEMETRY=off pi
+```
+
+## P1: code index và retrieval
+
+Index nằm tại:
+
+```text
+.pi/piagent-state/context-engine/context-v2.sqlite
+```
+
+Nó dùng SQLite FTS5 có sẵn trong Node.js `>=22.19.0`, không cần native package
+hoặc install script. File được nhận diện bằng SHA-256; lần refresh sau tái sử
+dụng record có `mtime` và size không đổi. `.gitignore`, binary, file quá lớn,
+secret file, protected paths, dependency/build output và toàn bộ guard state
+không được index.
+
+Symbol layer hiện dùng parser adapter zero-dependency cho TypeScript/JavaScript,
+Python, Go, Rust, Java/Kotlin/C#, C/C++, Swift, Dart, Ruby, PHP, Elixir, Lua,
+SQL và Markdown. Schema parser-neutral để có thể thêm Tree-sitter sau này mà
+không migrate consumer. Tree-sitter không phải dependency mặc định vì native
+grammar size và install reliability phải thắng benchmark trước khi rollout.
+
+Candidate ranking gồm:
+
+1. Explicit path/basename.
+2. FTS5 BM25 lexical match.
+3. Exact và partial symbol match.
+4. Current Git changes.
+5. Test filename/path relation.
+6. Positive-only session feedback.
+7. Personalized PageRank trên import graph.
+
+Các ranked list được hợp nhất bằng Reciprocal Rank Fusion:
+
+```text
+score(file) = sum(weight(source) / (60 + rank(source, file)))
+```
+
+Context pack tách repo map và source snippets, sau đó dừng cứng tại token
+budget. Index chỉ là navigation evidence; model phải đọc file hiện tại trước
+khi edit.
+
+## P2: compaction, finder và test impact
+
+- `/context impact` đi ngược import graph từ file thay đổi và tìm test liên quan.
+- Context pack trả `high`, `medium`, `low`, hoặc `none` confidence.
+- Với `low/none`, runtime đề xuất đúng một bounded read-only finder pass, không
+  tự spawn và không tự đổi model.
+- `/context compact` giữ goal, acceptance criteria, quyết định, invariant,
+  changed files, verify evidence, blocker và next action. Nó loại log thô,
+  repeated reads, kế hoạch đã bị thay thế và source excerpt có thể đọc lại.
+
+## P3: Agent Watch telemetry và feedback
+
+Event append-only nằm tại:
+
+```text
+.pi/piagent-state/context-engine/events.jsonl
+.pi/piagent-state/context-engine/efficiency-report.json
+```
+
+Mỗi event có:
+
+```json
+{
+  "schemaVersion": 1,
+  "source": "piagent",
+  "recordedAt": "ISO-8601",
+  "event": "agent_prompt | tool_activation | context_pack | tool_call | tool_result | turn_end | session_compact",
+  "sessionId": "Pi session id",
+  "sessionName": "operator session name",
+  "model": "provider/model",
+  "thinkingLevel": "off|minimal|low|medium|high|xhigh"
+}
+```
+
+Agent Watch có thể join event với Pi session JSONL bằng `sessionId` và
+`sessionName`. Không cần polling realtime; import lúc mở app hoặc lúc xuất
+report vẫn thấy đủ event đã ghi.
+
+Feedback không phải model học ngầm. Khi một context pack chọn file và chính
+session đó sau đó thực sự đọc hoặc sửa file, file nhận một boost nhỏ ở những
+lần retrieval sau. File chưa có lịch sử hoặc từng được chọn nhưng chưa dùng
+không bị trừ điểm. `contextSelections`, `contextSelectionsUsed` và
+`contextUtilizationRate` trong efficiency report cho phép audit hiệu quả của
+ranking. Runtime chỉ đọc phần đuôi telemetry có giới hạn khi tính report hoặc
+feedback, nên lịch sử dài không làm chậm từng prompt theo thời gian.
+
+`contextWasteScore` nằm trong khoảng `0..100`, thấp hơn là tốt hơn:
+
+```text
+30% duplicate read rate
+25% duplicate output rate
+20% tool schema share
+15% low-confidence retrieval rate
+10% active-tool excess
+```
+
+Đây là operational signal, không phải quality verdict. Report phải đối chiếu
+với task gate, acceptance result, verify evidence, token usage và rework.
+
+## Sử dụng
+
+Trong Pi:
+
+```text
+/context index
+/context rebuild
+/context search <symbol or keyword>
+/context pack <task>
+/context impact [changed files]
+/context efficiency
+/usage efficiency
+```
+
+Ngoài terminal, không chạy model:
+
+```bash
+piagent-context status
+piagent-context rebuild
+piagent-context search calculateInvoiceTotal
+piagent-context pack "Fix invoice total calculation" --tokens 4000
+piagent-context impact src/invoice.ts
+piagent-context efficiency
+```
+
+## Benchmark gate
+
+So sánh cùng task, repository commit, model, thinking và verify command. Mỗi
+variant chạy ít nhất ba lần. Chỉ bật mặc định khi:
+
+- acceptance/pass rate không giảm;
+- rework và failed verification không tăng;
+- fresh input tokens, duplicate reads và time-to-first-correct-edit giảm;
+- protected-path, secret-redaction và final-gate tests vẫn pass.

package/docs/context-window-policy.md

@@ -4,19 +4,20 @@
 
 Không nhồi toàn bộ repo vào context. Agent phải load đúng lớp context theo task.
 
-Lần đầu gắn project vào platform, chạy `/onboard run` sau login/model selection để tạo `.pi/project-context.md` và `.pi/context-index.json`. Các task sau dùng context index như bản đồ nhỏ để tìm đúng vùng cần đọc, rồi vẫn verify bằng files task-specific hiện tại.
+Lần đầu gắn project vào platform, chạy `/onboard run` sau login/model selection để tạo `.pi/project-context.md`, `.pi/context-index.json` và local Context Engine index. Các task sau dùng index như bản đồ nhỏ để tìm đúng vùng cần đọc, rồi vẫn verify bằng files task-specific hiện tại.
 
 ## Context order
 
 1. `AGENTS.md` gần project nhất.
 2. Project profile: `.pi/piagent-profile.json`.
-3. Project context index: `.pi/context-index.json` nếu tồn tại và không stale.
-4. Project context snapshot: `.pi/project-context.md`.
-5. Memory summary nếu profile bật memory và task liên quan: `.pi/memory/memory_summary.md`.
-6. Required context từ profile.
-7. Task-specific files.
-8. Related tests/docs.
-9. External docs only khi cần và ưu tiên official docs.
+3. Context Engine pack cho task unfamiliar/cross-module nếu index tồn tại và không stale.
+4. Project context index: `.pi/context-index.json` nếu tồn tại và không stale.
+5. Project context snapshot: `.pi/project-context.md`.
+6. Memory summary nếu profile bật memory và task liên quan: `.pi/memory/memory_summary.md`.
+7. Required context từ profile.
+8. Task-specific files.
+9. Related tests/docs.
+10. External docs only khi cần và ưu tiên official docs.
 
 Trước khi ghi context manifest hoặc dự định đưa file lớn vào prompt, dùng:
 
@@ -30,6 +31,7 @@ Trước task lớn/risk cao trong Pi TUI:
 
 ```text
 /context preflight
+/context pack <task>
 /context compact
 ```
 
@@ -72,6 +74,8 @@ Pi settings template dùng:
 - Không paste full mandatory-flow boilerplate vào task hằng ngày; platform prompts/tools đã chứa flow đó.
 - Nếu context vượt budget, tạo summary theo module thay vì nhồi full files.
 - Dùng `/context search` hoặc `piagent_context_index_search` để tìm điểm vào repo, nhưng không dùng index thay thế việc đọc source thật.
+- Dùng `/context rebuild` sau structural changes; incremental refresh tái sử dụng file không đổi.
+- Context pack low-confidence chỉ được mở rộng bằng một bounded finder pass, không loop scout vô hạn.
 - Không raw-read hoặc raw-edit `.pi/context-index.json` trong task thường ngày. Runtime coi index là advisory state, sanitize khi đọc qua tool/command, và ghi qua `/onboard run` hoặc `piagent_context_index_record`.
 - File context vượt hard cap phải được summarize hoặc đọc targeted slices, không inject full.
 - Nếu input quá dài thật, lưu intake vào file project/local gitignored rồi reference file; không dán toàn bộ spec vào một turn.
@@ -79,6 +83,7 @@ Pi settings template dùng:
 - Tool output dài chỉ nên hiện preview. Dùng `/logs` hoặc command targeted hơn để debug; không paste full test/build log vào chat/final.
 - Memory chỉ là hint. Phải verify bằng source hiện tại trước khi sửa code.
 - Context index cũng chỉ là hint. Nó có node/edge/citation để giảm scout lại, không phải security boundary hoặc source of truth.
+- Context Engine telemetry chỉ lưu operational metadata/hash dưới `.pi/piagent-state/`; prompt và tool output thô vẫn nằm trong Pi session/audit source hiện có.
 
 ## Nguồn
 

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.4` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.6` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.4` |
+| Registry distribution | `npm:@piagent/platform@1.2.6` |
 | 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.4` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.6` | 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.4
+pi install git:github.com/Vt-mmm/piagent@v1.2.6
 ```
 
 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.4
+npm install -g --ignore-scripts @piagent/platform@1.2.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.4` 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.4`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.6` 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.6`.
 
 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.4 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.6 \
   --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.4
+npm install -g --ignore-scripts @piagent/platform@1.2.6
 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.4`. 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.6`. 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.4
+npm install -g --ignore-scripts @piagent/platform@1.2.6
 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.4 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.6 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -894,8 +894,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.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.4` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.6` | 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. |
@@ -1002,7 +1002,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.4
+npm install -g --ignore-scripts @piagent/platform@1.2.6
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -55,6 +55,10 @@ pi install /path/to/piagent
 - `1.2.0`: `piagent-mcp` quản lý server đầy đủ, server do repo mang theo phải được duyệt mới dùng được, và `/piagent-mcp` là command trong session chứ không phải nhờ model chạy bash.
 - `1.2.1`: approval gate thật sự phủ direct tool và server đến qua `imports` — hai đường vòng mà bản `1.2.0` để hở; kèm một loạt fix về containment khi vendor, độ sâu shell guard, và credential trong URL.
 - `1.2.2`: tool output dài được compact vào preview trong Pi và capture local cho Agent Watch/report; thêm `/setname` và `/logs` cho session naming và log audit gọn.
+- `1.2.3`: gom command hằng ngày về `/workflow`, `/usage`, `/context`, `/permission`, `/onboard`, `/name` và `/fresh`.
+- `1.2.4`: update global có fallback về user-writable npm prefix và project migration/doctor là bước hậu kiểm tùy chọn.
+- `1.2.5`: updater đọc đúng metadata singleton-array của npm 12.
+- `1.2.6`: Context Engine v2, dynamic tool loading, hard-budget retrieval, semantic compaction, Agent Watch telemetry/feedback và quality benchmark theo context efficiency.
 
 ## Không publish
 

package/docs/quality-benchmark.md

@@ -41,7 +41,12 @@ bash scripts/quality-benchmark.sh /path/to/project --record \
   --surface pi \
   --result pass \
   --tokens 8200 \
+  --input-tokens 6900 \
+  --output-tokens 1300 \
+  --cache-read-tokens 2400 \
   --duration 540 \
+  --first-correct-edit 210 \
+  --rework 0 \
   --notes "good plan, no edits"
 ```
 
@@ -58,8 +63,14 @@ Output:
 | `result` | `pass`, `fail`, hoặc `partial` theo verify và acceptance criteria. |
 | `surface` | Agent surface/workflow/model preset được dùng cho run. |
 | `tokens` | Tổng token do runtime/provider báo. |
+| `inputTokens` | Fresh input token, tách khỏi cache read để so context thực. |
+| `outputTokens` | Token model sinh ra. |
+| `cacheReadTokens` | Input được provider phục vụ từ prompt cache. |
 | `cost` | Cost nếu provider báo được. |
 | `durationSeconds` | Thời gian wall-clock. |
+| `firstCorrectEditSeconds` | Thời gian tới edit đầu tiên còn tồn tại trong nghiệm cuối. |
+| `reworkCount` | Số lượt edit bị bỏ hoặc phải làm lại. |
+| `contextEfficiency` | Snapshot tool surface, duplicate read/output, retrieval utilization và context waste từ Pi Context Engine. |
 | `notes` | Số lần sửa lại, missing context, wrong file, verify failure, hoặc quality observation. |
 
 ## Quy tắc claim
@@ -71,4 +82,6 @@ Chỉ claim một setup tốt hơn khi:
 - cùng verify command;
 - ít nhất 3 lần chạy hoặc 3 scenario khác nhau;
 - pass rate không thấp hơn setup hiện tại;
-- token/cost giảm mà không tăng manual rework.
+- fresh input token/cost giảm mà không tăng manual rework;
+- time-to-first-correct-edit giảm hoặc không xấu đi;
+- context waste giảm nhưng acceptance và verify vẫn giữ nguyên.

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.4 | Rollout guidance |
+| Surface | Status for v1.2.6 | 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.4` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.6` | 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.4
+npm install -g --ignore-scripts @piagent/platform@1.2.6
 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.4 (helper package version)
-tag: v1.2.4
+currentRelease: v1.2.6 (helper package version)
+tag: v1.2.6
 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.4
+pi install git:github.com/Vt-mmm/piagent@v1.2.6
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/runtime-harness-standard.md

@@ -24,7 +24,7 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 |---|---|---|
 | Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
 | Intake | `piagent_task_start` | Mỗi task có scope, output, acceptance criteria trước khi edit. |
-| Context rules | `/onboard run`, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
+| Context rules | `/onboard run`, Pi Context Engine, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
 | Test matrix | `verifyCommands` + observed verify evidence | DONE phải có exact verify command thực chạy qua Pi bash hoặc `N/A` rõ lý do. |
 | Trace | `piagent_trace_record`, `.pi/piagent-state/traces.jsonl`, session entry | Có audit trail cho task. |
 | Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
@@ -52,6 +52,9 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
 
 ## Task lifecycle chuẩn
 
+Vòng đời thích nghi theo mức rủi ro. Runtime guard luôn hoạt động, nhưng các
+tool context mang tính advisory chỉ được nạp khi task thực sự cần.
+
 ```text
 1. Intake
    - risk lane
@@ -61,10 +64,10 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
    - protected paths
 
 2. Context
-   - load piagent_context
-   - read `.pi/project-context.md`
-   - read requiredContext
-   - check large files with piagent_context_budget
+   - load concise piagent_context once
+   - use one token-budgeted Context Engine pack for unfamiliar/cross-module work
+   - read only targeted requiredContext
+   - check only large/unfamiliar files with piagent_context_budget
    - record context manifest
 
 3. Plan
@@ -73,8 +76,8 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
    - rollback/handoff if high-risk
 
 4. Implement
-   - check risky shell with piagent_exec_policy_check
-   - check non-piagent tools with piagent_tool_policy_check
+   - check complex/risky shell with piagent_exec_policy_check
+   - check non-piagent tools only when capability is unclear
    - edit only in scope
    - avoid protected paths
 
@@ -92,6 +95,12 @@ Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecy
    - piagent_task_gate_check before DONE
 ```
 
+| Lane | Extra context/orchestration |
+|---|---|
+| `tiny` | Core lifecycle only; parent agent, targeted reads, exact verify. |
+| `normal` | Index/memory only for unfamiliar areas; bounded read-only delegation when it saves context. |
+| `high-risk` | Relevant index/memory/vendor evidence plus explicit security/data/release review. |
+
 ## Maturity phases
 
 | Phase | Output | Đủ để implement task? |

package/docs/security-threat-model.md

@@ -21,7 +21,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.4, 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.6, 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