@piagent/platform 1.3.1 → 1.4.1

package/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## Unreleased
+
+## v1.4.1 - 2026-08-17
+
+- Local installs now synchronize the terminal helper and WebUI Gateway from the same checkout before registering the Pi package, preventing a stale global Gateway from enforcing older session/task lifecycle rules.
+
+### Integrity boundary
+
+- The runtime integrity graph skipped shell entrypoints entirely, so a pinned command could execute an unpinned program: `piagent-usage` ran a 567-line reader of `~/.pi/agent/sessions/**` that the lock had never seen, because the path was built from `$SCRIPT_DIR` and the repository-relative literal never appeared in the source. Shell sources are now scanned, and a sibling reached through a computed directory is followed.
+
+- The published package ships the built browser bundle and not the sources it came from, so on an installed platform that 725 KB of JavaScript could not be regenerated or checked against anything — while it runs inside the origin that holds the session cookie and the CSRF token, with the authority to drive session commands, source mutation and provider auth. The server that serves it was pinned; what it served was not. The served bundle is now pinned, document included, because the document names which script runs.
+
+- A TypeScript module imported by its emitted name — `./x.js` for `x.ts`, the ordinary TypeScript convention — resolved to nothing and was dropped in silence. No module was outside the lock because of it, but a module that decides what the guard enforces could have been, while the graph still claimed to be complete.
+
+### Agent control
+
+- Command-only test/build/typecheck/package requests now enter an execution-capable governed task even when the operator forbids source edits; read-only remains a strict inspection mode instead of failing halfway through the first verifier command.
+
+- A terminal Task Contract used to terminate the conversation with it: WebUI swallowed the next operator message before Pi persisted it, the Gateway could only report `session-command-effect-unknown`, and `piagent_task_start` then demanded a fresh Pi session. Conversations may now bind sequential Task Contracts. The closed task remains immutable, paused/stopping tasks remain closed, and the terminal boundary admits only new conversation input plus the exact successor-task start transition.
+
+- `OwnedWorkCeilings` advertised eight limits and six of them were never read: the per-role ceilings were real but fixed at one apiece, so raising `maxScoutPasses` in a profile did nothing while `maxTotalHelpers` beside it took effect. Half-honoured configuration reads as working configuration. The ceilings are now read from the object the caller passes; every default is one, so no shipped behaviour changes, and automatic mode is pinned against widening.
+
+- A blocked tool call is the only conversation most operators have with this policy, and it was one-sided: of 43 distinct refusals, three said what to do next. Remedies are now attached at the single point every decision leaves through, so a refusal added later is answered without anyone remembering to. The refusal that stops the whole session says which command explains it.
+
+- `piagent explain '<command>'` reports conclusive static refusals and the guard readers that found them. A static pass is now explicitly `indeterminate` until the live Pi runtime evaluates Task Contract, scope, permission, lifecycle, approval and budget state; the standalone CLI can no longer issue an "exact allow" that the real guard later blocks. `--scope` lists the static boundary in effect.
+
+### Redaction and evidence
+
+- An npm token was recognised only where something named it, so `//registry.npmjs.org/:_authToken=npm_…` — the whole of an `.npmrc`, and what a failing publish prints — went through unredacted. Every other provider here is matched by the shape of its token.
+
+- Redaction runs before tool-result compaction, and that order was the only thing keeping a credential out of the capture written to project state. Nothing pinned it; reversing the two calls would have written credentials to disk and passed every test.
+
+- An observation that states neither an exit code nor an error flag no longer satisfies a claim of success. It is unreachable through the recorded shapes, but a reader of the function that guards forged verification should not have to prove that.
+
+### Cost and clarity
+
+- `piagent-usage` reports fresh tokens and the cache hit rate, using the benchmark's own definition of a fresh token so the terminal and the published measurement cannot mean two different things. The rate is reported beside the count and never instead of it: in the published benchmark the baseline surface held the higher hit rate while spending more than twice the fresh tokens.
+
+- Capability verification derived the ancestor set on every cache hit, which at 296 pinned files cost more than every `lstat` it performed put together. Deriving it once per snapshot took a hit from 4.28 ms to 1.61 ms with no loss of tamper detection.
+
+- The WebUI opens in the language the browser asked for instead of always starting in Vietnamese; the confirmation for full access focuses the safe choice, so a reflex Enter dismisses it rather than granting it; and the file a diff shows is derived from the list that is loaded, so no later clear can leave the pane asking for a file beside a list holding one.
+
+### Install and uninstall
+
+- Running the documented two-command install downgraded the machine-wide Pi package to whatever pin the project being initialised happened to carry, including a project the operator only meant to open once. One resolved value served both scopes and read the project pin first, so a pin that is authority over its own project quietly became authority over the machine. The two scopes now resolve separately: the global install takes the running helper, the project keeps its pin, an explicit `--package-source` still beats both, and a divergence between them is printed instead of silently resolved.
+
+- Uninstall removed nothing on any machine whose helper sits under a non-default npm prefix — the fallback the installer takes when the configured global root is not writable, and whatever `piagent-update --npm-prefix` was given. `npm uninstall -g` resolves against the configured prefix, so the run exited `0` and reported completion over an install that was still there. The prefix is now derived from where the running helper actually is, the same way the updater derives it, and the follow-up command printed for the operator to copy carries that prefix too. An npx cache root is still never claimed, because it owns no bin on anyone's PATH.
+
+### Agent control coverage
+
+- A stop request only counts as pending if its `commandId` is truthy, so an empty one records the stop and then reports nothing pending — the single outcome an operator pressing stop must never get. The journal writers never check the shape, and the only thing preventing it was a regex in the browser command validator that no test named. Malformed identifiers are now pinned as rejected at that boundary, together with the proof that a well-formed one still passes, so the guard cannot be loosened or widened into blanket refusal without a test failing.
+
+### The dashboard starts without the MCP adapter
+
+- `piagent dashboard` could not start on any machine where `pi-mcp-adapter` was not installed under the agent directory — an install run with `--no-mcp`, or anyone trying the package through `npx` before setting anything up. The gateway is spawned with `PIAGENT_PINNED_TS_TRANSFORM_ROOT` pointing at that adapter, and the TypeScript loader called `realpath` on it before deciding anything. That function answers one question — is the file being loaded inside the pinned adapter — and it threw instead of answering "no", so the throw escaped the loader on the first `.ts` file of any kind and killed the process. It now answers "no", which falls back to `strip`: the stricter of the two modes, so this can only ever refuse a transform, never grant one. The exception for the reviewed adapter, its exact version, and containment within its root are all unchanged.
+
+- The failure was also unreadable. The gateway child was spawned with its stderr discarded, so a process that died on its first line looked exactly like a slow one: twelve seconds of waiting, then `gateway-start-timeout` and nothing else. The child's stderr is now kept, bounded, and reported, an early exit stops the wait instead of running out the clock, and the two cases are named differently — a process that died and a process that never answered are different problems.
+
+### Bilingual documentation
+
+- The language gate proved a Vietnamese peer existed, which is not the same as saying the same thing: editing the English side and forgetting the other passed every check in this repository, and left a reader with a document describing a design that had changed. Each pair now records the content digest of both sides as of the last time somebody confirmed them consistent, and a side that moves alone fails the gate naming the file that has to follow. A two-sided edit is reported separately, because it is probably a paired edit and calling it drift would teach people to skip the gate. What it cannot do is read the two documents and decide they agree; it records that a human looked.
+
+### Google Workspace and document conversion
+
+- Added Google's own remote MCP servers for Drive, Gmail, Docs and Sheets, one per product rather than a single server holding every scope, because that separation is the point: reading a spreadsheet should not cost a grant over Drive and every document in it, let alone the mailbox. Each has its own preset, so the narrowest useful grant is always available.
+- Google Workspace MCP is Developer Preview and has no credentialed Pi OAuth E2E proof in this release. The four entries are marked experimental, print that status through catalog/preset output, and stay out of the generic `documents` preset as well as every default preset. Official endpoints and readonly scopes remain available through explicitly named Google presets for controlled testing.
+
+- None of them appear in `core` or `popular`. `core` is what an install writes when nobody names a preset and `popular` is what people pick without reading the list, so an entry in either would hand an operator mail and file access they never chose. A test fails if one leaks in, if a catalog server exposes direct tools instead of going through the approval gate, or if a server that needs credentials ships without saying so.
+
+- Connecting Gmail changes the threat model rather than extending it: until now the untrusted input reaching an agent was source code, and it becomes any mail anyone can send. The approval gate still stands between a message and an action, but the documentation now states plainly what the product cannot prevent, and recommends read-only scopes and the narrowest preset.
+
+- Added MarkItDown for converting local `.docx`, `.xlsx`, `.pptx`, `.pdf` and `.html` to Markdown. It runs offline for `file:` URIs, which is the reason to prefer it: a document worth converting is usually one worth not uploading. It is pinned at its published alpha, and needs `uv`.
+
+### Adoption measurement
+
+- GitHub serves repository traffic as a rolling 14-day window and discards everything older, with no endpoint that returns it. `traffic-snapshot` archives clones, views, referrers and paths daily into growing CSV files on a separate `traffic-data` branch, so the history survives and the product branch is not buried under a row a day. A day still filling when the run happens is overwritten by the next run rather than frozen partial, and a gap under 14 days loses nothing. The traffic endpoints need push access, so a 403 names the exact fix — a fine-grained token with `Administration: read` stored as `TRAFFIC_TOKEN` — instead of leaving a nightly job red.
+
+- The documentation site now carries Vercel Web Analytics, which is cookieless and stores no browser identifier, so the site still owes no consent banner. The snippet is emitted from the site shell rather than any page, so both locales and every future page inherit it, and a test fails if a generated page ships without it or if a script from another origin appears. The runtime remains free of any network call: `telemetry()` writes locally and the package has no install hook.
+
+### Documentation parity
+
+Four documents restated something the code already knew, and each had drifted. They are now checked against their source, so the next drift fails a test instead of reaching a reader.
+
+- `install-global.sh --help` omitted `--default-model` and `--subagents-model-scope`, which had been accepted for four releases. The help text now carries every flag with its valid values, and the parity check reads the flag list out of the parser.
+
+- The `piagent-usage --json` documentation described two of the six top-level keys. `scope`, `projects`, `tools` and `generatedAt` were undocumented, including the record of which filters produced the report — without which a saved report cannot explain itself. All six are documented with their fields, and compared against the emitted object in both directions.
+
+- The architecture documents listed nine physical layers while `architecture/layers.json` enforced fifteen: every WebUI layer was enforced and undocumented, in both languages. The seven are now described with what they own and may not own, alongside why they form a second dependency spine rather than a branch of the first.
+
+- The team release history stopped at `1.2.11` while releases continued to `1.4.0`, and `1.1.1` had been skipped earlier. Twelve entries were added, and the list is now checked against the changelog from its own oldest entry forward, so a gap anywhere in it fails.
+
+- The repository layout in the README showed one package where there are two, leaving `piagent-webui` — the dashboard, its client, server, gateway and ownership layers — invisible to anyone reading the map before the tree.
+
+## 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

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.
 
@@ -272,12 +272,18 @@ piagent/
 ├─ evals/                            governed evaluation scenarios
 ├─ packs/                            versioned capability manifests and recipes
 ├─ packages/
-│  └─ piagent-core/               Pi package: extensions, prompts, skills
+│  ├─ piagent-core/                  Pi package: extensions, runtime, prompts, skills
+│  └─ piagent-webui/                 dashboard: contracts, client, server, gateway, ownership
 ├─ schemas/                          JSON schemas
 ├─ scripts/                          setup, doctor, verification helpers
 └─ templates/                        project/global templates
 ```
 
+`piagent-core` is the Pi extension and runs headless on its own. `piagent-webui` is the
+`piagent dashboard` surface — a separate dependency spine that reads the platform but is
+never read by it, so the runtime keeps working with the dashboard absent. Both layer maps
+are enforced by `npm run architecture:check`; see [Architecture](docs/en/architecture.md).
+
 ## Verification
 
 One command runs the full local gate — typecheck, tests, capability catalog, doctor, and the scaffold check:
@@ -343,7 +349,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.1` 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.1` or a reviewed commit.
 
 Ready for:
 

package/README.vi.md

@@ -84,6 +84,30 @@ npm run architecture:check
 - [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, prompt, skill
+│  └─ piagent-webui/                  dashboard: contract, client, server, gateway, ownership
+├─ schemas/                           JSON schema
+├─ scripts/                           setup, doctor và helper kiểm tra
+└─ templates/                         template project/global
+```
+
+`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).
+
 ## Adaptive model routing
 
 Adaptive model routing cho fresh task dùng `piagent-route --prompt "<task>" --json`.
@@ -98,6 +122,9 @@ npm run verify
 
 Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
 
+Bản phát hành hiện tại là `v1.4.1`. 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.
+
 ## Security
 
 Pi Agent Platform là application-level policy layer, không phải OS sandbox. Với untrusted code hoặc adversarial workload, vẫn cần container hoặc VM có filesystem, process, network và credential boundary riêng.

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
 

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.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.3.1` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.4.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.4.1` | 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.1` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.4.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.3.1` |
+| Registry distribution | `npm:@piagent/platform@1.4.1` |
 | 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.1` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.4.1` | 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.1
+pi install git:github.com/Vt-mmm/piagent@v1.4.1
 ```
 
 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.1
+npm install -g --ignore-scripts @piagent/platform@1.4.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.3.1` 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.1`.
+`pi install git:github.com/Vt-mmm/piagent@v1.4.1` 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.1`.
 
 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.1 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.4.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/en/architecture.md

@@ -43,9 +43,22 @@ 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 |
+| WebUI contracts | `packages/piagent-webui/contracts/` | Wire types shared by browser and server | Any runtime behavior; it depends on nothing |
+| WebUI client | `packages/piagent-webui/client/` | Browser views, view models, UI preferences | Server state, filesystem, Pi APIs |
+| WebUI server | `packages/piagent-webui/server/` | HTTP/WS endpoints, session reads, diff assembly | Browser rendering; it may not import the client |
+| WebUI extension | `packages/piagent-webui/extension/` | The in-Pi `/piagent-webui` command surface | Wire types the client also needs |
+| WebUI gateway | `packages/piagent-webui/gateway/` | Standalone `piagent dashboard` process, port and lifecycle | Feature logic that belongs to the server |
+| WebUI ownership | `packages/piagent-webui/ownership/` | Single-owner claims over a session directory | Transport and rendering; it depends on nothing |
+| WebUI build | `packages/piagent-webui/` (package root) | Bundling the client and packaging the served assets | Source of any one WebUI layer |
 | Entrypoints | `scripts/` | CLI arguments and use-case invocation | Duplicate domain logic |
 | Product assets | `prompts/`, `skills/`, `subagents/`, `adapters/`, `packs/`, `schemas/` | Declarative behavior and contracts | Hidden runtime state |
 
+The WebUI layers are a second dependency spine, not a branch of the first. `contracts` and
+`ownership` sit at the bottom and import nothing; `client` may only reach `contracts`, so the
+browser bundle can never pull in server or Pi code. `server`, `extension`, and `gateway` reach
+down into `runtime`/`core`/`security` — never the reverse, so the platform runs headless with
+the WebUI absent. `npm run architecture:check` enforces every edge above.
+
 `extensions/` still contains several historical service modules. The name is legacy; only `piagent-guard.ts` is loaded as a Pi extension. Services move by cohesive feature, with compatibility preserved until the migration is complete.
 
 ## Runtime flow

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/languages.json

@@ -19,22 +19,38 @@
     {
       "topic": "repository-readme",
       "en": "README.md",
-      "vi": "README.vi.md"
+      "vi": "README.vi.md",
+      "consistentAt": {
+        "en": "03bcb10e6bb051fe2ccf9feeb6bf9bb9eec99bc0",
+        "vi": "a7eba50acf4215883d704af10c9df0cd69f06599"
+      }
     },
     {
       "topic": "documentation-index",
       "en": "docs/en/README.md",
-      "vi": "docs/vi/README.md"
+      "vi": "docs/vi/README.md",
+      "consistentAt": {
+        "en": "659e68ecd362bbef6cbce5a4b3fa86d4bd52f2a4",
+        "vi": "d8686c9e11aa79faecae658d7275ca14c628de18"
+      }
     },
     {
       "topic": "architecture",
       "en": "docs/en/architecture.md",
-      "vi": "docs/vi/architecture.md"
+      "vi": "docs/vi/architecture.md",
+      "consistentAt": {
+        "en": "5bcb0aa311b360408ca73425744baee71e740a9b",
+        "vi": "b613cec25fa1737636121c11cb2c5aecb2e00375"
+      }
     },
     {
       "topic": "maintainer-guide",
       "en": "docs/en/maintainer-guide.md",
-      "vi": "docs/vi/maintainer-guide.md"
+      "vi": "docs/vi/maintainer-guide.md",
+      "consistentAt": {
+        "en": "e04ab2a64da66c59fbc2f52b472db481815c6ea5",
+        "vi": "8ce84e7221156cfa3882e29d50045be989d1ea7d"
+      }
     }
   ]
 }