@piagent/platform 1.1.8 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.2.0 - 2026-07-28
+
+### Added
+
+- `piagent-mcp` manages servers instead of only seeding presets: `add`, `remove`, `get`, `list`, `enable`, `disable` and `doctor`, across the four config layers via `--scope`. `add` reports which scope it wrote and the exact file it changed, so nobody has to guess which layer is in effect. A server added by hand keeps surviving `piagent-update`, because a preset only rewrites the server IDs it owns.
+
+- A server a repository defines is not usable until somebody on this machine approves it. `.mcp.json` and `.pi/mcp.json` travel with a clone, and opening a session in one should not hand its author a process here with this operator's credentials. `piagent-mcp approve` prints the definition before recording the decision, `reject` and `reset` are the other two answers, and the decision is stored in `~/.pi/piagent-mcp-approvals.json` rather than in the repository — a repository that can approve its own servers has not been gated.
+
+  The record pins the digest of what was approved. Approval is consent to what the server runs, so changing its command, URL or arguments returns it to pending, which is the same split the capability lock draws between consent and build.
+
+  Enforcement is in the guard's `tool_call` hook, covering both the `mcp` proxy and the `mcp__<server>__<tool>` form that `directTools` produces. The adapter owns the connection and the extension cannot prevent one being opened, so what is stopped is every tool call, not the connection itself. Servers in the global layers are not gated: nothing a repository contains can put a server there.
+
+- MCP is a command inside a session, not a request to the model. `/piagent-mcp` on its own opens a menu, because a surface only helps if it can be found without already knowing the subcommand. The menu is built from what the project has: approving is not offered when nothing is waiting on a decision, and each entry carries its own count. Picking an action that needs a server asks which one, unless there is only one it could be.
+
+  Every entry is also typeable — `status`, `get`, `doctor`, `approve`, `reject`, `reset`, `enable`, `disable` — and both paths run the same code, so the menu teaches the direct form instead of replacing it. Subcommands and server names autocomplete. Where no prompt can be answered, in print and JSON mode, the report and the subcommand list are printed rather than blocking on a question nobody can answer.
+
+  Typing the shell command mid-session asked the model to run bash, read the output and report back — three model turns for a question this process answers from files it has already read, and a different summary each time. Pi dispatches a registered command straight to its handler, so the model is not involved at all.
+
+  Adding and removing a server stay in the terminal: `add` carries shell quoting, `${VAR}` references and a `--` command line. Those already have one correct parser, and it is the shell; a slash command that re-implemented it would be a second, worse one. `/piagent-mcp add` prints the terminal command rather than guessing at one.
+
+  Both surfaces read the same module, so the two cannot disagree about whether a server is usable. Remedies name the form that works where they are read: the session prints `/piagent-mcp approve <name>`, the terminal prints `piagent-mcp approve <name>`.
+
+- `piagent-mcp doctor` and `piagent-doctor` say what each configured server still needs — a referenced variable that is not exported, an executable that is not on PATH, a decision that has not been made, the Docker daemon not answering. Counting configured servers, which is what the doctor did before, says nothing about whether any of them can answer. A session start names the ones that are definitely stuck; `PIAGENT_NO_MCP_NOTICE=1` switches that off.
+
+### Changed
+
+- `piagent-mcp add` refuses to write a credential into MCP config and prints the reference form to use instead. The check reads both the field name and the value, so `--env CONFIG=ghp_...` is caught as well as `--env GITHUB_TOKEN=...`, and it covers `--header` too. `--url` accepts https, or http only on loopback. `list` and `get` mask values while leaving `${VAR}` readable, because that is a variable name rather than its contents.
+
+  OAuth is not automated and no token is stored by this platform. Pi already owns that flow — `/mcp-auth <server>` — and a third credential store holding other people's credentials would be worse than either of the two that already exist.
+
+- `scripts/configure-mcp.sh` is replaced by `scripts/mcp-manage.mjs`; the pinned server catalog moved into `packages/piagent-core/mcp/`, where the capability lock pins it. The `piagent-mcp` command is unchanged. The three MCP files that decide which servers a session may call are now part of the locked runtime set.
+
+- The docs site is one page per topic instead of a single file, grouped in the sidebar as Get started, Build, MCP and Operate. MCP has four pages of its own, since it now has a command surface, an approval decision and an auth story to explain. Each page carries a table of contents and previous/next links.
+
+  Pages are generated by `scripts/build-docs-site.mjs` from a content fragment each, plus shared `docs-site/assets/docs.css` and `docs-site/assets/docs.js`. The generated HTML is committed, because the site is served as static files with no build step, and `npm run verify` fails when the committed output no longer matches its source. `npm run site:preview` serves the result the way the deployment does — the site relies on clean URLs, so an ordinary static server answers 404 for every internal link.
+
+- Public text describes this platform on its own terms rather than against named competing products. The page that compared feature tables now states what the platform takes on and what it leaves to the host, and is called Phạm vi platform rather than carrying two other products' names in the sidebar of every page. The same wording pass covers the MCP pages, `docs/mcp-and-tools.md` and a design-rationale comment in `document-intake.ts`.
+
+  Where "Codex" and "Claude" mean model families they are now labelled as such, with their provider ids, so a reader cannot mistake a model choice for a different tool. `--model-scope` and `--preset` say "model families" in their help text for the same reason.
+
+  The wording gate in `npm run verify` only read `README.md`, `docs/`, the prompts and the project template, which is why the site and the runtime strings were never checked. It now also reads `docs-site/content`, the site builder — navigation labels live there, not in a fragment — and the `mcp` and `extensions` directories that print to an operator.
+
+## v1.1.9 - 2026-07-28
+
+### Fixed
+
+- The update notice reaches the install path people actually use. v1.1.8 decided a platform tree was a maintainer's working copy when it found a `.git` directory in it — but `pi install git:...` clones the repository, so an ordinary install carries a `.git` and every other file a working copy carries. There is no mark inside the tree that separates them, which meant the notice never appeared for anyone who installed the documented way.
+
+  What separates them is where they sit: Pi puts packages it installed under its own agent directory, and npm puts the global helper under `node_modules`. A tree anywhere else is a working copy and is still told nothing. `PI_CODING_AGENT_DIR` is honoured, and both paths are resolved before comparison, because a home reached through a symlink is ordinary — macOS reaches `/var` that way — and comparing a real path against a symlinked one made an install look like it was somewhere else.
+
 ## v1.1.8 - 2026-07-28
 
 ### Added
@@ -233,7 +283,7 @@ Breaking release. The `company` namespace is replaced by `piagent` with no alias
 
 ### Changed
 
-- Clarified public docs comparison with Codex CLI and Claude Code: Pi Company Platform brings similar governance concepts into Pi and packages them for team workflows.
+- Clarified in the public docs where this platform sits relative to a general agent coding CLI: Pi Company Platform brings similar governance concepts into Pi and packages them for team workflows.
 - Reworded security docs to describe the guard as an application-level policy enforcement layer, not a complete security boundary or OS sandbox.
 - Split install guidance so production/team setup uses pinned `v0.4.8` or resolved commit sources, while latest is reserved for personal/sandbox use.
 - Clarified that redaction benchmarks and internal review are not equivalent to an external security audit.

package/README.md

@@ -248,7 +248,7 @@ This repository intentionally excludes:
 ## Documentation
 
 - [Public docs site](https://piagent.io.vn)
-- [Static team docs site](docs-site/index.html)
+- [Static team docs site](docs-site/index.html) — generated from `docs-site/content/`, preview with `npm run site:preview`
 - [Changelog](CHANGELOG.md)
 - [Vercel docs site deploy](docs/vercel-docs-site.md)
 - [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md)
@@ -283,7 +283,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.1.8` 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.0` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -222,7 +222,7 @@ Các command này thuộc Pi core hoặc package Pi chính. Tên/availability c
 
 | Command/hotkey | Dịch nghĩa | Dùng khi nào | Ghi chú |
 |---|---|---|---|
-| `/login` | Đăng nhập provider | Lần đầu dùng OpenAI/Codex hoặc Anthropic/Claude. | OAuth/session lưu local trong Pi, không commit repo. |
+| `/login` | Đăng nhập provider | Lần đầu dùng model OpenAI Codex hoặc model Anthropic Claude. | OAuth/session lưu local trong Pi, không commit repo. |
 | `/model` | Chọn model | Muốn chọn OpenAI provider bằng native selector. | Đây là flow chính, không phải hỏi agent tự chọn thay. |
 | `Ctrl+L` | Mở model selector | Đổi model nhanh. | Tương đương UI selector của Pi. |
 | `/scoped-models` | Chỉnh danh sách model cycle | Muốn `Ctrl+P` chỉ xoay quanh vài model hay dùng. | Global setup seed sẵn provider model families. |
@@ -237,6 +237,15 @@ Các command này thuộc Pi core hoặc package Pi chính. Tên/availability c
 | `/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. |
+| `/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. |
+| `/piagent-mcp doctor` | Server nào chưa chạy được và thiếu gì | Sau khi cài, hoặc khi tool call MCP bị chặn. | Không probe Docker daemon; chạy `piagent-mcp doctor` ở terminal cho việc đó. |
+| `/piagent-mcp approve <name>` | Duyệt server repo khai | Khi mở một repo có `.mcp.json`. | In định nghĩa ra trước khi ghi quyết định. Pin theo digest. |
+| `/piagent-mcp reject <name>` | Từ chối | Không tin server repo khai. | `reset` để quên quyết định. |
+| `/piagent-mcp enable\|disable <name>` | Bật/tắt server | Tắt tạm mà không mất định nghĩa. | Cần `/reload` để adapter nhận thay đổi. |
+
+`/piagent-mcp` chạy thẳng trong session, không qua model. Thêm/xoá server và preset ở terminal: `piagent-mcp add|remove|--preset`.
 
 ## Command subagent
 
@@ -419,8 +428,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.1.8` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.8` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.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 một lệnh: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. Thêm `--project <path>` để chạy doctor sau. |
@@ -478,7 +487,7 @@ Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứ
 | `npm run usage -- <project>` | `bash scripts/pi-session-stats.sh <project>` |
 | `npm run models` | `bash scripts/pi-model-catalog.sh` |
 | `npm run model-scope -- --preset full` | `bash scripts/configure-model-scope.sh --preset full` |
-| `npm run mcp -- --preset core --scope global --replace` | `bash scripts/configure-mcp.sh --preset core --scope global --replace` |
+| `npm run mcp -- --preset core --scope global --replace` | `node scripts/mcp-manage.mjs --preset core --scope global --replace` |
 | `npm run subagents -- --preset safe` | `bash scripts/configure-subagents.sh --preset safe` |
 
 ## MCP command quick map

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.1.8` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.0` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.1.8` |
+| Registry distribution | `npm:@piagent/platform@1.2.0` |
 | 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.1.8` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.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 +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.1.8
+pi install git:github.com/Vt-mmm/piagent@v1.2.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 +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.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.1.8` 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.1.8`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.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.2.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).
 
@@ -103,7 +103,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.1.8 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/mcp-and-tools.md

@@ -18,11 +18,117 @@ Không có dòng code nào map capability name sang MCP server id. Khai `"github
 
 Từ `v0.3.7`, repo có thêm:
 
-- `piagent-mcp` / `scripts/configure-mcp.sh`;
+- `piagent-mcp` / `scripts/mcp-manage.mjs`;
 - MCP preset `core`, `popular`, `all`, `design`, `design-local`, `browser`, `docs`, `github`;
 - template `.mcp.json` project-shared;
 - doctor warning khi adapter có nhưng không có MCP server nào.
 
+## Hai bề mặt
+
+Trong session Pi thì dùng slash command, ngoài terminal thì dùng CLI. Cùng module đọc config, cùng cách phân loại trạng thái.
+
+| Việc | Trong session | Trong terminal |
+|---|---|---|
+| Mở menu | `/piagent-mcp` | — |
+| Danh sách + state | `/piagent-mcp status` | `piagent-mcp list` |
+| Chi tiết một server | `/piagent-mcp get <name>` | `piagent-mcp get <name>` |
+| Thiếu gì để chạy | `/piagent-mcp doctor` | `piagent-mcp doctor` |
+| Duyệt server của repo | `/piagent-mcp approve <name>` | `piagent-mcp approve <name>` |
+| Bật/tắt | `/piagent-mcp enable\|disable <name>` | `piagent-mcp enable\|disable <name>` |
+| Thêm/xoá/preset | — | `piagent-mcp add\|remove\|--preset` |
+| Kết nối live, OAuth | `/mcp`, `/mcp-auth <name>` | — |
+
+Slash command do Pi dispatch thẳng tới handler và **không đi qua model**: gõ `piagent-mcp list` giữa session là nhờ model chạy bash, đọc output rồi thuật lại — ba lượt model cho một câu hỏi process này trả lời được từ file nó đã đọc.
+
+Thêm và xoá server ở lại terminal: `add` mang shell quoting, tham chiếu `${VAR}` và một command line sau `--` — ba thứ đã có sẵn một bộ parse đúng là chính shell, viết lại bên trong slash command chỉ tạo ra bộ parse thứ hai tệ hơn. Gọi `/piagent-mcp add` sẽ in ra lệnh terminal tương ứng chứ không đoán.
+
+Gõ `/piagent-mcp` không tham số sẽ mở menu dựng theo đúng thứ project đang có — chưa server nào bị tắt thì không hiện "bật lại", không server nào chờ duyệt thì không hiện "approve". Chọn một việc cần server thì nó hỏi tiếp server nào, trừ khi chỉ có đúng một lựa chọn. Mọi mục trong menu đều gõ thẳng được, nên menu dạy dạng trực tiếp chứ không thay thế.
+
+Không có select UI (print mode `-p`, JSON mode) thì in thẳng bảng trạng thái + danh sách subcommand, không treo chờ trả lời.
+
+`/piagent-mcp` có auto-complete cho subcommand và tên server.
+
+## Quản lý server
+
+`piagent-mcp` có subcommand đầy đủ, không chỉ preset:
+
+```bash
+piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
+piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
+piagent-mcp list
+piagent-mcp get sentry
+piagent-mcp disable sentry          # giữ định nghĩa, chỉ tắt
+piagent-mcp remove sentry --scope global
+piagent-mcp doctor
+```
+
+`--scope` nhận `global`, `pi-global`, `project`, `pi-project` — ứng với 4 file ở bảng bên dưới. Mặc định `global`. `add` in ra scope và **đường dẫn file vừa sửa**, để không phải đoán config nào đang có hiệu lực.
+
+Server tự thêm sống sót qua mọi lần `piagent-update`: preset chỉ ghi đè đúng những server ID nó sở hữu. Ngược lại, sửa tay một server thuộc preset (`github`, `context7`…) sẽ bị `--replace` đưa về baseline ở lần update kế tiếp — muốn giữ bản riêng thì đặt tên khác.
+
+## Secret không bao giờ nằm trong config
+
+`add` **từ chối** giá trị trông giống credential và in ra dạng cần dùng:
+
+```bash
+$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
+FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
+written into MCP config. Export it in your shell and reference it instead:
+--env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'
+```
+
+Chặn theo hai lớp: tên field nghe như credential, và giá trị tự nó trông như secret (bắt được cả `--env CONFIG=ghp_...`). Áp dụng cho cả `--env` lẫn `--header`.
+
+`--url` chỉ nhận `https`, hoặc `http` khi host là loopback — Figma desktop MCP là đúng trường hợp đó.
+
+`list` và `get` mask giá trị; riêng `${VAR}` được in nguyên vì đó là **tên biến**, không phải nội dung.
+
+## 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:
+
+```text
+/mcp-auth figma
+```
+
+`/piagent-mcp doctor` (hoặc `piagent-mcp doctor` ngoài terminal) phân loại từng server:
+
+| State | Nghĩa |
+|---|---|
+| `ready` | đủ điều kiện, gọi được |
+| `needs-env` | config tham chiếu `${VAR}` mà biến chưa export (chỉ in **tên biến**) |
+| `needs-command` | executable không có trên PATH |
+| `pending-approval` | repo khai server này, chưa ai duyệt trên máy này |
+| `approval-changed` | đã duyệt nhưng định nghĩa đã đổi |
+| `rejected` | đã từ chối cho project này |
+| `disabled` | tắt bằng `/piagent-mcp disable` |
+| `oauth` | đăng nhập do Pi giữ; platform không biết còn hạn hay không |
+
+`oauth` **không** bị coi là lỗi, và không xuất hiện trong notice đầu session — platform không phân biệt được đã login hay chưa, nên báo mỗi session sẽ thành nhiễu.
+
+`doctor` chạy thêm `docker info` (chậm, nên chỉ ở doctor chứ không ở session start). `piagent-doctor` cũng đưa các state chặn vào `warnings`.
+
+## Approval gate cho server đến từ repo
+
+Repo mang theo được `.mcp.json` và `.pi/mcp.json`. Clone một repo lạ rồi mở session **không** được phép cho tác giả repo đó một process trên máy mình với credential của mình. Nên server ở hai scope này không dùng được cho tới khi có người trên máy này duyệt.
+
+```bash
+piagent-mcp get internal        # đọc trước
+piagent-mcp approve internal    # hoặc reject / remove
+```
+
+Ba tính chất quan trọng:
+
+- **Quyết định nằm ngoài repo** — `~/.pi/piagent-mcp-approvals.json`. Repo tự duyệt được cho mình thì gate coi như không có. Fork, đổi tên, checkout thứ hai đều bắt đầu lại từ `pending`.
+- **Pin theo digest của định nghĩa.** Duyệt là đồng ý với *thứ server đó chạy*; đổi command, URL hay args là câu hỏi mới, state quay về `approval-changed`. Cùng cách tách consent/build mà capability lock đang dùng.
+- **Enforce ở `tool_call`**, không phải ở config. Guard chặn cả proxy (`mcp` với `input.server`) lẫn dạng direct tool (`mcp__<server>__<tool>`) — gate chỉ đọc proxy sẽ bị đi vòng bằng cách bật `directTools`.
+
+Giới hạn cần nói thẳng: extension **không chặn được adapter mở connection**, chỉ chặn tool call. Phần còn lại là bản thân kết nối, và việc server phía kia ghi log rằng có người kết nối.
+
+Server ở `global` / `pi-global` không qua gate — hai layer đó nằm ngoài mọi repo, không repo nào đặt được server vào đó, và bắt duyệt config của chính mình trên từng máy là vô nghĩa.
+
+Notice đầu session nêu tên server đang chờ quyết định hoặc thiếu setup. Tắt bằng `PIAGENT_NO_MCP_NOTICE=1`.
+
 ## Cấu hình một lần cho máy cá nhân/team
 
 Cả `piagent-setup` và `piagent-install` đều cài adapter và seed preset `core` **mặc định**. Muốn bỏ qua thì thêm `--no-mcp`.
@@ -56,7 +162,7 @@ piagent-mcp --list
 Nếu clone repo GitHub và chưa link npm bin:
 
 ```bash
-bash /path/to/piagent/scripts/configure-mcp.sh --preset popular --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset popular --scope global --replace
 ```
 
 `--replace` cập nhật các server ID thuộc preset về baseline đã pin và vẫn giữ nguyên server ID khác. Luồng install/upgrade toàn cục luôn dùng chế độ này để không duy trì dependency động từ cấu hình cũ.

package/docs/model-options.md

@@ -1,6 +1,8 @@
 # Model selector and scope
 
-Pi Agent Platform không khóa vào một provider. OpenAI Codex và Claude/Anthropic đều là first-class option.
+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`).
+
+Lưu ý cách đọc: trong toàn bộ tài liệu này, "Codex" và "Claude" là **tên họ model** đứng sau các provider id ở trên. Chúng không phải tên CLI, và cũng không phải một agent nào khác — mọi thứ ở đây đều chạy trong Pi.
 
 Quan trọng: flow chính là user chọn model bằng native Pi selector, không phải hỏi agent recommend.
 
@@ -48,7 +50,7 @@ piagent-models --provider openai-codex
 piagent-models --provider anthropic
 ```
 
-Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, Claude có thể chưa hiện dù model catalog local có metadata.
+Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, các model Claude có thể chưa hiện dù model catalog local có metadata.
 
 ## Thinking levels
 
@@ -70,7 +72,7 @@ pi --thinking medium
 
 Đừng giới hạn vào vài ví dụ. Sau `pi update --models`, kiểm tra catalog local bằng `piagent-models`. Ở release hiện tại, các family/presets chính cần nhớ:
 
-### OpenAI Codex
+### Họ model OpenAI Codex
 
 | Model | Role gợi ý | Khi dùng |
 |---|---|---|
@@ -82,14 +84,14 @@ pi --thinking medium
 | `openai-codex/gpt-5.6-sol` | strategic/deep | architecture, large refactor, planning lớn |
 | `openai-codex/gpt-5.6-terra` | huge-context scout | đọc nhiều docs/source, tổng hợp repo lớn |
 
-### Claude / Anthropic
+### Họ model Claude (Anthropic)
 
 | Model | Role gợi ý | Khi dùng |
 |---|---|---|
 | `anthropic/claude-haiku-4-5` | fast/cheap | hỏi nhanh, docs/scout nhẹ |
 | `anthropic/claude-sonnet-4-5` | balanced | task source bình thường |
 | `anthropic/claude-sonnet-4-6` | balanced/deep | source task lớn hơn, max-capable |
-| `anthropic/claude-sonnet-5` | balanced/hard default | Claude default mạnh cho implement |
+| `anthropic/claude-sonnet-5` | balanced/hard default | model default mạnh cho implement |
 | `anthropic/claude-opus-4-5` | deep | review/refactor lớn |
 | `anthropic/claude-opus-4-6` | deep/max | architecture/reasoning nặng |
 | `anthropic/claude-opus-4-7` | deep/xhigh/max | high-risk/debug/architecture |
@@ -102,7 +104,7 @@ Pi catalog có thể có thêm dated variants như `*-2025xxxx`. Dùng alias lat
 
 Preset dưới đây là cách mình seed `enabledModels`, không phải giới hạn hard. User vẫn có thể mở `/model` để chọn bất kỳ model available nào trong provider catalog.
 
-| Preset | OpenAI Codex example | Claude/Anthropic example | Khi dùng |
+| Preset | Model OpenAI Codex | Model Claude (Anthropic) | Khi dùng |
 |---|---|---|---|
 | Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | đọc nhanh, hỏi đáp, grep/scout nhẹ |
 | Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | task source bình thường |
@@ -160,6 +162,6 @@ bash scripts/quality-benchmark.sh /path/to/project --record \
 
 So sánh tối thiểu:
 
-- Pi + Codex fast/balanced/deep;
-- Pi + Claude fast/balanced/deep;
+- Pi + model Codex ở fast/balanced/deep;
+- Pi + model Claude ở fast/balanced/deep;
 - any other approved setup nếu team muốn so sánh bằng số liệu.

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.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.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.1.8`. 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.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 +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.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -154,7 +154,7 @@ Trong Pi:
 /login
 ```
 
-Chọn provider/account như OpenAI/Codex hoặc Anthropic/Claude. Credential nằm trong Pi user dir, không nằm trong repo và không được commit.
+Chọn provider/account cho họ model muốn dùng: OpenAI (model Codex) hoặc Anthropic (model Claude). Credential nằm trong Pi user dir, không nằm trong repo và không được commit.
 
 Browser login của OpenAI có hai chỗ trông như treo. Cả hai là lỗi Pi host, không phải platform, và còn nguyên ở `0.82.0` lẫn `0.82.1`.
 
@@ -281,7 +281,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.1.8 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.0 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -298,7 +298,7 @@ Khi command không có trên PATH, dùng script trực tiếp:
 
 ```bash
 bash /path/to/piagent/scripts/init-project.sh /path/to/project --profile auto
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
 ```
 
@@ -654,7 +654,7 @@ piagent-mcp --list
 Fallback:
 
 ```bash
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 ```
 
 ### Cấu hình project
@@ -666,7 +666,7 @@ piagent-mcp --preset design --scope project --project /path/to/project
 Fallback:
 
 ```bash
-bash /path/to/piagent/scripts/configure-mcp.sh \
+node /path/to/piagent/scripts/mcp-manage.mjs \
   --preset design \
   --scope project \
   --project /path/to/project
@@ -854,8 +854,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.1.8` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.8` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.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. |
@@ -952,7 +952,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.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.0
 command -v piagent-install
 ```
 
@@ -960,7 +960,7 @@ Nếu đang làm việc từ source checkout, có thể dùng script trực ti
 
 ```bash
 bash /path/to/piagent/scripts/pi-session-stats.sh /path/to/project
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
 ```
 

package/docs/publishing-for-teams.md

@@ -51,6 +51,8 @@ pi install /path/to/piagent
 - `1.1.6`: `be-readonly-fe` giữ được backend read-only trong monorepo, detect FE/BE đọc cả workspace, và rule detect gộp về một chỗ.
 - `1.1.7`: update global không còn chặn project đang chạy — lock chỉ block khi grant thật sự đổi, và profile dạng `extends` nhận policy từ platform đang cài thay vì giữ bản copy lúc onboard.
 - `1.1.8`: Pi báo ngay ở đầu session khi có release mới, kèm lệnh chạy update.
+- `1.1.9`: notice update hiện đúng trên bản cài bằng `pi install git:` — bản cài nhận diện theo vị trí thư mục, không theo `.git`.
+- `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.
 
 ## Không publish
 

package/docs/quickstart-vietnamese.md

@@ -50,14 +50,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 OpenAI Codex/ChatGPT hoặc Claude/Anthropic
+## Bước 2 — login OAuth provider model (OpenAI/ChatGPT hoặc Anthropic)
 
 ```bash
 pi
 /login
 ```
 
-Chọn provider OpenAI/Codex/ChatGPT hoặc Anthropic/Claude trong danh sách Pi. Token được lưu local trong Pi agent dir, không nằm trong repo.
+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.
 
 ## Bước 3 — chọn model và chạy project onboarding
 

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

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.1.8, 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.0, 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

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.0
 piagent-install --stable
 cd /path/to/project
 pi
@@ -42,7 +42,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.8
+npm install -g --ignore-scripts @piagent/platform@1.2.0
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -70,7 +70,7 @@ piagent-update --check
 piagent-update --project /path/to/project
 ```
 
-`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.8`.
+`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.2.0`.
 
 Không cần ai nhớ đi kiểm tra: khi có release mới, Pi tự báo ngay ở dòng notice lúc mở session, kèm luôn lệnh chạy.
 
@@ -129,7 +129,7 @@ Nếu browser login của OpenAI trông như treo, xem [login provider](operator
 
 ## Bước 3 — chọn model và onboard project
 
-Sau login, chọn provider/model intended cho project understanding bằng native Pi selector. OpenAI Codex và Claude/Anthropic đều là supported option.
+Sau login, chọn provider/model intended cho project understanding bằng native Pi selector. Cả hai họ model đều là supported option: model OpenAI Codex và model Anthropic Claude.
 
 ```text
 /model          # hoặc Ctrl+L