@piagent/platform 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,9 +2,62 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
-## Unreleased
-
-No changes after the `v1.3.0` stable boundary.
+## v1.4.0 - 2026-08-15
+
+### Local Session Hub and WebUI
+
+- Added a local, one-per-profile Gateway and `piagent dashboard` experience for
+  creating, reopening, resuming, renaming, pinning, archiving, unarchiving, and
+  forking durable Pi sessions without starting an extra model turn for views.
+- Rebuilt the browser client as a conversation-first MUI application with a
+  compact composer, project and model controls, light/dark themes, Vietnamese
+  and English UI, responsive layouts, and an Agent Inspector for tasks, source
+  changes, activity, verification, usage, and handoff evidence.
+- Added exact Gateway-owned chat streaming, held-message queues, bounded
+  attachments, model/thinking controls, lifecycle controls, and Pi-owned
+  approval cards while preserving one authoritative writer per session.
+
+### Source review, recovery, and security
+
+- Added Task Changes, Working Tree, and Staged projections with bounded diffs,
+  provenance, criterion/verifier links, protected-path enforcement, and guarded
+  stage, unstage, revert, and editor handoff actions.
+- Added durable session leases, terminal compatibility ownership, restart and
+  stale-owner recovery, idempotent command receipts, replay/resync, doctor with
+  explicit repair, and corrupt-state fail-closed behavior.
+- Hardened the TypeScript loader, local control socket creation, runtime
+  integrity inventory, browser authentication, redaction, event bounds, and
+  provider/MCP credential handling.
+
+### Documentation and release gates
+
+- Classified every root operating document by language, retained canonical
+  English/Vietnamese entry points, and added a gate that rejects unclassified
+  or unindexed Vietnamese documentation.
+- Added a provider-neutral product-language gate while retaining third-party
+  names only where they describe real integrations, dependencies, or operator
+  commands.
+- Added the executable WUI5-18 release matrix covering durable sessions,
+  ownership, recovery, approvals, protected data, transport validation,
+  accessibility, themes, and zero-model-turn navigation.
+
+## v1.3.1 - 2026-08-13
+
+### Security and reliability hardening
+
+- Extended the capability integrity inventory to include the TypeScript loader,
+  CLI dispatcher, and the remaining task-state, verification, and backend
+  decision modules that can affect runtime enforcement.
+- Replaced repeated full-file capability hashing on every tool call with a
+  fail-closed metadata cache. Session start may re-pin an unchanged grant to a
+  new installed build; build drift discovered during a running session blocks
+  that session until restart instead of silently rewriting its lock.
+- Removed shell interpolation from the `pdftotext` availability probe while
+  preserving the existing PDF extraction behavior.
+- Made local JSONL state locks publish their complete owner atomically and
+  recover a hard-killed normal writer without exposing an empty lock. Recovery
+  ownership is deliberately fail-closed: if that recovery process itself is
+  killed, an operator must remove its `.recovery` lock before writes resume.
 
 ## v1.3.0 - 2026-08-12
 

package/README.md

@@ -248,8 +248,8 @@ Handled by Pi's native UI: `/model` or `Ctrl+L` to pick, `Ctrl+P` to cycle the s
 | Preset | Includes |
 |---|---|
 | `core` | Context7, Chrome DevTools, GitHub |
-| `popular` | core + Playwright + Figma remote |
-| `all` | popular + Figma desktop/local |
+| `popular` | core + Playwright + Figma desktop/local |
+| `all` | popular + Figma remote (requires an approved Figma MCP client) |
 
 Seeding writes server definitions; it does not start or authenticate anything. Servers connect lazily, so each one needs its own prerequisite before its first call: Chrome DevTools needs a local Chrome, and GitHub needs Docker running plus `GITHUB_PERSONAL_ACCESS_TOKEN` exported. `piagent-mcp --list` prints what each server requires. Project-scope `.mcp.json` files ship empty on purpose — the shared baseline is the global config, not the project one.
 
@@ -343,7 +343,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.3.0` 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.4.0` or a reviewed commit.
 
 Ready for:
 

package/architecture/layers.json

@@ -43,6 +43,48 @@
         "packages/piagent-core/benchmark"
       ]
     },
+    {
+      "name": "webui-contracts",
+      "roots": [
+        "packages/piagent-webui/contracts"
+      ]
+    },
+    {
+      "name": "webui-client",
+      "roots": [
+        "packages/piagent-webui/client"
+      ]
+    },
+    {
+      "name": "webui-server",
+      "roots": [
+        "packages/piagent-webui/server"
+      ]
+    },
+    {
+      "name": "webui-extension",
+      "roots": [
+        "packages/piagent-webui/extension"
+      ]
+    },
+    {
+      "name": "webui-gateway",
+      "roots": [
+        "packages/piagent-webui/gateway"
+      ]
+    },
+    {
+      "name": "webui-ownership",
+      "roots": [
+        "packages/piagent-webui/ownership"
+      ]
+    },
+    {
+      "name": "webui-build",
+      "roots": [
+        "packages/piagent-webui"
+      ]
+    },
     {
       "name": "entrypoints",
       "roots": [
@@ -86,6 +128,49 @@
     "benchmark": [
       "benchmark"
     ],
+    "webui-contracts": [
+      "webui-contracts"
+    ],
+    "webui-client": [
+      "webui-client",
+      "webui-contracts"
+    ],
+    "webui-server": [
+      "webui-server",
+      "webui-contracts",
+      "runtime",
+      "core",
+      "security",
+      "benchmark"
+    ],
+    "webui-extension": [
+      "webui-extension",
+      "webui-server",
+      "webui-ownership",
+      "runtime",
+      "core",
+      "security"
+    ],
+    "webui-gateway": [
+      "webui-gateway",
+      "webui-ownership",
+      "webui-server",
+      "webui-contracts",
+      "runtime",
+      "core",
+      "security"
+    ],
+    "webui-ownership": [
+      "webui-ownership"
+    ],
+    "webui-build": [
+      "webui-build",
+      "webui-contracts",
+      "webui-client",
+      "webui-server",
+      "webui-gateway",
+      "webui-ownership"
+    ],
     "entrypoints": [
       "entrypoints",
       "runtime",
@@ -93,7 +178,10 @@
       "mcp",
       "capabilities",
       "security",
-      "benchmark"
+      "benchmark",
+      "webui-gateway",
+      "webui-ownership",
+      "webui-server"
     ]
   },
   "lineBudgets": {
@@ -105,6 +193,13 @@
       "capabilities": 1200,
       "security": 400,
       "benchmark": 1000,
+      "webui-contracts": 2000,
+      "webui-client": 500,
+      "webui-server": 500,
+      "webui-extension": 500,
+      "webui-gateway": 500,
+      "webui-ownership": 500,
+      "webui-build": 500,
       "entrypoints": 800
     },
     "files": {

package/docs/README.md

@@ -1,4 +1,5 @@
 # Documentation languages
+<!-- language: en+vi -->
 
 [English](en/README.md) | [Tiếng Việt](vi/README.md)
 

package/docs/architecture.md

@@ -1,4 +1,5 @@
 # Architecture documentation
+<!-- language: en+vi -->
 
 - [English architecture](en/architecture.md)
 - [Architecture tiếng Việt](vi/architecture.md)

package/docs/authority-manifest.md

@@ -1,4 +1,5 @@
 # Capability authority manifest
+<!-- language: en -->
 
 The capability authority manifest is the versioned policy source for Piagent
 1.3 tasks. It includes every shipped capability without granting every

package/docs/auto-delegation-policy.md

@@ -1,4 +1,5 @@
 # Solo-first orchestration policy
+<!-- language: vi; english-index: docs-site/content/en/workflows.html -->
 
 Mục tiêu: user không phải nhớ `/run`, `/parallel`, `/chain` cho workflow hằng ngày, nhưng platform cũng không tự biến mọi task thành swarm tốn token. Khi anh gõ `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, giữ mặc định **solo-first**, rồi chỉ dùng subagents nếu việc đó giúp giảm nhiễu context, tăng tốc read-heavy work, hoặc tăng chất lượng review. Alias cũ như `/task` vẫn giữ cùng policy.
 

package/docs/capability-packs.md

@@ -1,4 +1,5 @@
 # Capability packs
+<!-- language: vi; english-index: docs-site/content/en/scope.html -->
 
 ## Tổng quan
 
@@ -178,7 +179,7 @@ Lock pin hai thứ khác nhau, và khi lệch thì câu trả lời cũng khác
 - `packs` — name, version, origin, source, owner, lifecycle và digest của manifest. Manifest khai luôn `provides`, nên artifact xuất hiện thêm, biến mất hoặc đổi path đều nằm ở nhánh này;
 - permission theo hướng: granting key (`capabilities`, `filesystemRead`, `filesystemWrite`, `networkDomains`, `externalActions`) chặn khi **thêm**; restricting key (`protectedPaths`, `readOnlyPaths`, `shellProtectedPaths`) chặn khi **mất**.
 
-**Build — platform đổi bản, lock được ghi lại và báo, session chạy tiếp (`repin`):**
+**Build — platform đổi bản, lock chỉ được ghi lại tại session start có kiểm soát (`repin`):**
 
 - `core.packageVersion`, `core.runtimeFiles`, `core.packageDigest`;
 - nội dung artifact (`artifacts[].digest`).
@@ -187,6 +188,13 @@ Vì sao nội dung artifact nằm ở nhánh build: adapter policy file, base po
 
 Việc pin build cũng chưa bao giờ chống được trường hợp nó trông giống: code kiểm tra lock chính là một trong các file mà lock pin, nên thứ gì sửa được platform đã cài thì sửa luôn được checker.
 
+Session start thực hiện full verification và có thể ghi lại build mới nếu grant
+không đổi. Sau khi session đã bind với một build digest, drift mới phát hiện giữa
+phiên sẽ chặn tool call và yêu cầu restart; một session khác re-pin build mới
+không làm session cũ tự chuyển identity. Mỗi tool call vẫn kiểm tra integrity,
+nhưng đường bình thường dùng fingerprint metadata mạnh; bất kỳ thay đổi, lỗi
+metadata, symlink hoặc catalog/profile/lock drift nào đều quay lại full hash.
+
 ## Lifecycle
 
 | Trạng thái | Ý nghĩa |
@@ -249,7 +257,7 @@ Khai source không cấp quyền gì. Pack ngoài vẫn phải qua `capabilityPo
 ## Giới hạn hiện tại
 
 - Catalog là local file, chưa có remote discovery service. Catalog chỉ chứa pack của platform; pack ngoài xuất hiện trong lock của project.
-- Lock là preflight và integrity contract; runtime guard xác minh lại trước mỗi tool call đối với profile hiện hành. `PIAGENT_PROFILE` trusted override và legacy profile chưa khai `capabilityPacks` nằm ngoài lock gate; khi lock lỗi chỉ nhóm recovery/read-only tool giới hạn được phép hoạt động.
+- Lock là preflight và integrity contract; runtime guard kiểm tra lại trước mỗi tool call đối với profile hiện hành, dùng cache metadata fail-closed và full hash khi cache không còn hợp lệ. `PIAGENT_PROFILE` trusted override và legacy profile chưa khai `capabilityPacks` nằm ngoài lock gate; khi lock lỗi chỉ nhóm recovery/read-only tool giới hạn được phép hoạt động.
 - Eval scenario mới có schema và validation; execution matrix được triển khai ở phase tiếp theo.
 - Recipe binding nội bộ và eval scenario ID được kiểm tra trong exact dependency graph; capability binding vẫn do runtime tool registry giải quyết.
 - External action proposal chỉ được validate; authorization, artifact byte verification và executor có credential không nằm trong phạm vi này.

package/docs/command-reference-vietnamese.md

@@ -1,4 +1,5 @@
 # Command reference tiếng Việt
+<!-- language: vi; english-index: docs-site/content/en/commands.html -->
 
 > Nếu cần flow đầy đủ theo thứ tự dùng thật, đọc `docs/operator-manual-vietnamese.md`. File này chỉ là bảng tra cứu command.
 
@@ -309,7 +310,7 @@ Các command này thuộc Pi core hoặc package Pi chính. Tên/availability c
 | `/mcp setup` | Setup/refresh MCP | Khi MCP chưa nhận config. | Tùy adapter/version. |
 | `/mcp tools` | List MCP tools | Muốn biết server expose tool nào. | Dùng trước khi bảo agent gọi tool ngoài. |
 | `/mcp reconnect` | Kết nối lại MCP | Khi server lỗi, token mới, hoặc config đổi. | Không thay thế việc export secret env. |
-| `/mcp-auth figma` | OAuth Figma MCP | Khi dùng Figma remote MCP. | Có thể khác theo Figma/Pi MCP package version. |
+| `/mcp-auth figma` | OAuth Figma remote MCP | Chỉ dùng khi Piagent đã được duyệt trong Figma MCP Catalog. | Nếu bị từ chối client, dùng `figma-desktop`. |
 | `/piagent-mcp` | Menu MCP | Không nhớ subcommand, hoặc muốn xem có việc gì cần làm. | Menu dựng theo project; không có select UI thì in thẳng bảng trạng thái. |
 | `/piagent-mcp status` | Danh sách MCP server + state | Muốn biết server nào đang có, ở scope nào, sẵn sàng chưa. | Đọc config, không kiểm tra kết nối live — cái đó là `/mcp`. |
 | `/piagent-mcp get <name>` | Chi tiết một server | Trước khi duyệt, hoặc khi không rõ scope nào đang có hiệu lực. | Giá trị credential bị mask; `${VAR}` in nguyên vì là tên biến. |
@@ -501,8 +502,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.84.1` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.3.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.3.0` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.4.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.4.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. |
@@ -533,7 +534,7 @@ Các lệnh này chạy ngoài Pi.
 | `piagent-route --prompt-file <file> --execute --yes -- --approve` | Explicit prelaunch adaptive task; giữ hard pin và fail closed nếu preflight/catalog không đủ. |
 | `piagent-model-scope --preset full` | Re-apply full provider model scope. |
 | `piagent-mcp --preset core --scope global --replace` | Apply the governed MCP core baseline: Context7, Chrome DevTools, GitHub. |
-| `piagent-mcp --preset popular --scope global --replace` | Apply the governed MCP popular baseline: core + Playwright + Figma remote. |
+| `piagent-mcp --preset popular --scope global --replace` | Apply the governed MCP popular baseline: core + Playwright + Figma desktop. |
 | `piagent-mcp --list` | List MCP presets. |
 | `piagent-subagents --preset safe` | Re-apply subagent safe config. |
 | `pi install npm:pi-web-access@0.17.0` | Cấp web/search/fetch tools cho builtin `researcher`; platform setup/update cài mặc định từ `v1.2.8`. |

package/docs/context-engine.md

@@ -1,4 +1,5 @@
 # Pi Context Engine
+<!-- language: vi; english-index: docs-site/content/en/context-engine.html -->
 
 ## Mục tiêu
 

package/docs/context-window-policy.md

@@ -1,4 +1,5 @@
 # Context-window policy
+<!-- language: vi; english-index: docs-site/content/en/runtime.html -->
 
 ## Mục tiêu
 

package/docs/distribution-standard.md

@@ -1,4 +1,5 @@
 # Distribution standard
+<!-- language: vi; english-index: docs-site/content/en/team.html -->
 
 ## Nguyên tắc
 
@@ -14,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.3.0` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.4.0` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.3.0` |
+| Registry distribution | `npm:@piagent/platform@1.4.0` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +27,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.3.0` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.4.0` | 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 +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.3.0
+pi install git:github.com/Vt-mmm/piagent@v1.4.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.
@@ -65,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@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.3.0
+npm install -g --ignore-scripts @piagent/platform@1.4.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.3.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.3.0`.
+`pi install git:github.com/Vt-mmm/piagent@v1.4.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.4.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).
 
@@ -120,7 +121,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.3.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.4.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/herdr-workflow.md

@@ -1,4 +1,5 @@
 # Herdr workflow
+<!-- language: vi; english-index: docs-site/content/en/workflows.html -->
 
 ## Mục tiêu
 

package/docs/mcp-and-tools.md

@@ -1,4 +1,5 @@
 # MCP và tool policy
+<!-- language: vi; english-index: docs-site/content/en/mcp.html -->
 
 ## Kết luận hiện tại
 
@@ -85,12 +86,14 @@ Chặn theo hai lớp: tên field nghe như credential, và giá trị tự nó
 
 ## Login vào account MCP
 
-Platform **không tự chạy OAuth và không giữ token**. `pi-mcp-adapter` đã sở hữu luồng đó — nó đăng ký `/mcp` và `/mcp-auth`, giữ callback server và OAuth provider — và dựng kho credential thứ ba cho credential của bên khác là lựa chọn tệ hơn. Việc của platform là phát hiện và chỉ đường:
+Platform **không tự giữ token**. WebUI chỉ điều phối luồng OAuth do `pi-mcp-adapter` sở hữu; adapter giữ callback server, OAuth provider và credential store. Remote server vẫn có thể giới hạn client nào được phép đăng ký.
 
 ```text
-/mcp-auth figma
+/mcp-auth <approved-remote-server>
 ```
 
+Figma Desktop không cần OAuth. Figma Remote chỉ dùng được sau khi Piagent có trong Figma MCP Catalog.
+
 `/piagent-mcp doctor` (hoặc `piagent-mcp doctor` ngoài terminal) phân loại từng server:
 
 | State | Nghĩa |
@@ -227,7 +230,7 @@ Trong Pi:
 /mcp setup
 /mcp tools
 /mcp reconnect
-/mcp-auth figma
+/mcp-auth <approved-remote-server>
 ```
 
 ## MCP config layers
@@ -257,12 +260,12 @@ Quy ước của platform:
 | `docs` | Context7 | docs mới của framework/library |
 | `browser` | Chrome DevTools, Playwright | inspect UI/runtime/browser automation |
 | `github` | GitHub MCP | issue/PR/repo/release workflow |
-| `design` | Figma remote | design-to-code qua Figma OAuth |
-| `design-local` | Figma desktop | Figma desktop Dev Mode MCP local |
+| `design` | Figma desktop | design-to-code qua Figma desktop Dev Mode MCP |
+| `design-local` | Figma desktop | alias tương thích cho preset local cũ |
 | `web` | Context7, Chrome DevTools, Playwright | FE/web workflow |
 | `core` | Context7, Chrome DevTools, GitHub | default team baseline |
-| `popular` | core + Playwright + Figma remote | baseline nhiều team dev dùng |
-| `all` | popular + Figma desktop | đầy đủ, dùng khi muốn sẵn cả local Figma |
+| `popular` | core + Playwright + Figma desktop | baseline nhiều team dev dùng |
+| `all` | popular + Figma remote | thêm cấu hình remote cho client đã được Figma duyệt |
 
 ## Server baseline
 
@@ -300,7 +303,7 @@ export CONTEXT7_API_KEY=ctx7sk_...
 
 ### Figma
 
-Remote MCP:
+Remote MCP (chỉ dùng được khi client đã được Figma duyệt trong MCP Catalog):
 
 ```json
 {
@@ -331,7 +334,9 @@ Local desktop MCP:
 
 Khuyến nghị thực tế:
 
-- dùng remote Figma MCP khi account/org hỗ trợ OAuth;
+- Piagent mặc định dùng desktop local vì Figma Remote hiện chỉ chấp nhận các client có trong Figma MCP Catalog;
+- lỗi `mcp-oauth-client-not-approved` nghĩa là Figma từ chối đăng ký client, không phải lỗi account hay token của người dùng;
+- dùng remote Figma MCP sau khi Piagent được Figma duyệt;
 - dùng desktop local khi cần selection-based Dev Mode trong app Figma;
 - nếu muốn Pi-native thay vì MCP, có thể cài `pi install npm:pi-mono-figma@0.2.2` sau khi hoàn tất security và license review.
 

package/docs/memory-policy.md

@@ -1,4 +1,5 @@
 # Memory policy cho Pi Agent Platform
+<!-- language: vi; english-index: docs-site/content/en/runtime.html -->
 
 ## Tóm tắt quyết định
 

package/docs/model-options.md

@@ -1,4 +1,5 @@
 # Model selector and scope
+<!-- language: vi; english-index: docs-site/content/en/quickstart.html -->
 
 Pi Agent Platform không khóa vào một provider. Hai họ model dưới đây đều là first-class option: **model OpenAI Codex** (provider id `openai-codex`) và **model Claude của Anthropic** (provider id `anthropic`).
 

package/docs/oauth-providers.md

@@ -1,4 +1,5 @@
 # OAuth providers trong Pi
+<!-- language: vi; english-index: docs-site/content/en/mcp-auth.html -->
 
 ## Mục tiêu
 

package/docs/operator-manual-vietnamese.md

@@ -1,4 +1,5 @@
 # Pi Agent Platform - Operator manual tiếng Việt
+<!-- language: vi; english-index: docs-site/content/en/index.html -->
 
 ## Mục tiêu
 
@@ -18,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@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.3.0
+npm install -g --ignore-scripts @piagent/platform@1.4.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.3.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.4.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:
 
@@ -99,7 +100,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1
-npm install -g --ignore-scripts @piagent/platform@1.3.0
+npm install -g --ignore-scripts @piagent/platform@1.4.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -282,7 +283,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.3.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.4.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -821,12 +822,12 @@ session mới để usage/prompt/change evidence không bị trộn.
 | `docs` | Context7 | Cần docs framework/library mới. |
 | `browser` | Chrome DevTools, Playwright | FE/browser/runtime inspection. |
 | `github` | GitHub MCP | Issue/PR/repo/release workflow. |
-| `design` | Figma remote | Design-to-code qua Figma OAuth. |
-| `design-local` | Figma desktop | Figma Dev Mode local selection. |
+| `design` | Figma desktop | Design-to-code qua Figma Dev Mode local. |
+| `design-local` | Figma desktop | Alias tương thích cho preset local cũ. |
 | `web` | Context7 + browser tools | Web/FE default. |
 | `core` | Context7, Chrome DevTools, GitHub | Team baseline. |
-| `popular` | core + Playwright + Figma remote | Full dev baseline. |
-| `all` | popular + Figma desktop | Cần cả remote + local design. |
+| `popular` | core + Playwright + Figma desktop | Full dev baseline. |
+| `all` | popular + Figma remote | Thêm remote cho client đã được Figma duyệt. |
 
 ### Cấu hình global
 
@@ -864,9 +865,11 @@ node /path/to/piagent/scripts/mcp-manage.mjs \
 /mcp setup
 /mcp tools
 /mcp reconnect
-/mcp-auth figma
+/mcp-auth <approved-remote-server>
 ```
 
+`figma-desktop` không cần OAuth. Figma Remote chỉ chấp nhận client đã được duyệt trong Figma MCP Catalog.
+
 ### Config layers
 
 | File | Scope | Ghi chú |
@@ -1039,8 +1042,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.3.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.3.0` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.4.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.4.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. |
@@ -1152,7 +1155,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.3.0
+npm install -g --ignore-scripts @piagent/platform@1.4.0
 command -v piagent-install
 ```
 

package/docs/package-architecture-notes.md

@@ -1,4 +1,5 @@
 # Package architecture notes
+<!-- language: en -->
 
 This path is retained for stable links. The maintained architecture documents are:
 

package/docs/project-adapters.md

@@ -1,4 +1,5 @@
 # Project adapters
+<!-- language: vi; english-index: docs-site/content/en/profiles.html -->
 
 ## Mục tiêu
 

package/docs/project-onboarding.md

@@ -1,4 +1,5 @@
 # Project onboarding snapshot
+<!-- language: vi; english-index: docs-site/content/en/team.html -->
 
 ## Mục tiêu
 

package/docs/publishing-for-teams.md

@@ -1,4 +1,5 @@
 # Publish cho team dùng
+<!-- language: vi; english-index: docs-site/content/en/team.html -->
 
 ## Mục tiêu
 

package/docs/quality-benchmark.md

@@ -1,4 +1,5 @@
 # Quality benchmark guide
+<!-- language: vi; english-index: docs-site/content/en/benchmark.html -->
 
 ## Chạy và chấm tự động bằng một lệnh
 

package/docs/quickstart-vietnamese.md

@@ -1,4 +1,5 @@
 # Quickstart tiếng Việt
+<!-- language: vi; english-index: docs-site/content/en/quickstart.html -->
 
 > Nếu cần hướng dẫn đầy đủ từ setup, command, token/session, MCP đến subagents, xem `docs/operator-manual-vietnamese.md`.
 
@@ -50,14 +51,14 @@ Xong. Từ đây project nào cũng chỉ cần `cd` vào rồi gõ `pi`.
 
 Rollout team pin từng bước, update, rollback, và channel `--dev` cho máy cá nhân: [release-install-policy.md](release-install-policy.md).
 
-## Bước 2 — login OAuth provider model (OpenAI/ChatGPT hoặc Anthropic)
+## Bước 2 — login OAuth provider model đã chọn
 
 ```bash
 pi
 /login
 ```
 
-Chọn provider cho họ model muốn dùng trong danh sách Pi: OpenAI/ChatGPT cho model Codex, hoặc Anthropic cho model Claude. Token được lưu local trong Pi agent dir, không nằm trong repo.
+Chọn đúng provider được Pi liệt kê cho model cần dùng và hoàn tất flow OAuth tương ứng. Token được lưu local trong Pi agent dir, không nằm trong repo.
 
 ## Bước 3 — chọn model và chạy project onboarding