@piagent/platform 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.1.6 - 2026-07-27
+
+Monorepo fixes found auditing how the platform scopes itself to a project. Every case was reproduced against a real directory tree before it was changed.
+
+### Fixed
+
+- `be-readonly-fe` keeps the backend read-only in a monorepo. Its `readOnlyPaths` and `shellProtectedPaths` were anchored at the repository root, so `backend/**` and `apps/api/**` covered a backend sitting at the top of the tree and nothing else. Choosing the profile on a repository whose backend lives in `packages/api`, `apps/backend` or `services/payments` produced a profile that announced the backend was read-only while leaving every file in it writable — the one guarantee the profile exists to make. The backend directories under `apps/`, `packages/` and all of `services/*` are covered now.
+
+  They are enumerated rather than matched with `**/api/**`, which would have swept in `packages/web/src/api/` — the frontend's own HTTP client — and frozen the half of the repository the profile is meant to leave writable.
+
+- The frontend verify command finds a frontend that is not at `frontend/` or `apps/web/`. It fell through to the repository root, where a workspace root has no `type-check` script, so verification reported success having run nothing. `apps/frontend`, `packages/web`, `packages/frontend` and `client` are looked at too.
+
+- `apps/backend` is read as a backend. `apps/frontend` counted as a frontend marker while only `apps/api` and `apps/server` counted as backend ones, so a repository that named both halves symmetrically was detected as frontend-only and offered `web-frontend`. `client/` and `server/` at the root were not markers either.
+
+- Frontend and backend are detected inside declared workspaces. Nothing read the `workspaces` field or `pnpm-workspace.yaml`, and nothing looked under `packages/`, so a pnpm monorepo fell through every marker to `generic`. Each declared package is now read through its own manifest and layout, which is what identifies `packages/storefront` and `packages/gateway` as the two halves of a fullstack repository. Only a trailing wildcard is expanded, absolute and `..` patterns are refused, and at most 64 packages are read.
+
+### Changed
+
+- Profile detection lives in `packages/piagent-core/extensions/project-shape.js`. `piagent_profile_options` and `scripts/init-project.sh` each carried their own copy of the rules and had drifted; the `apps/backend` gap above was present in both, and a fix to either would have left the other wrong. The file is covered by the capability lock, because steering which profile a project is offered is a way to choose what the guard ends up enforcing.
+
+## v1.1.5 - 2026-07-27
+
+### Added
+
+- `piagent-update` moves a machine from one release to the next in one command. A release is three independently versioned things — the Pi host, the npm-global terminal helper, and the Pi package — and they have to move in that order, because `piagent-install` refuses to run against a host that does not match the version its own package.json pins and does not install one itself. Doing it by hand is three commands and one ordering rule that fails late when it is got wrong.
+
+  Every version the run needs is resolved from the registry before anything is installed, including the host version taken from the *target* helper's published metadata rather than the running one, so `--check` and `--dry-run` describe exactly what a real run would do. After the helper replaces itself the run confirms that the version on disk is the one it asked for, and stops before touching the Pi package if it is not. Running it from a git checkout is refused rather than replacing that checkout's commands with a published build.
+
+  `--check`, `--dry-run`, `--version X.Y.Z`, `--force`, `--project <path>`, `--no-host`, `--no-package`, and pass-through to `piagent-install` after `--`.
+
+### Fixed
+
+- `docs/release-install-policy.md`, `docs/team-onboarding.md` and `docs/command-reference-vietnamese.md` described the manual update sequence without saying why its order is mandatory. `piagent-install` fails on a host mismatch; the auto-install of a matching host lives in `setup.sh` and does not apply to that flow.
+
 ## v1.1.4 - 2026-07-27
 
 ### Fixed

package/README.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.4` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.1.6` or a reviewed commit.
 
 Ready for:
 

package/adapters/be-readonly-fe/profile.json

@@ -32,7 +32,11 @@
     "api/**",
     "apps/api/**",
     "apps/server/**",
-    "services/backend/**",
+    "apps/backend/**",
+    "packages/api/**",
+    "packages/server/**",
+    "packages/backend/**",
+    "services/*/**",
     "**/migrations/**"
   ],
   "shellProtectedPaths": [
@@ -47,7 +51,11 @@
     "api/**",
     "apps/api/**",
     "apps/server/**",
-    "services/backend/**",
+    "apps/backend/**",
+    "packages/api/**",
+    "packages/server/**",
+    "packages/backend/**",
+    "services/*/**",
     "**/migrations/**",
     "**/node_modules/**",
     "**/dist/**",
@@ -85,10 +93,10 @@
       "test -s README.md"
     ],
     "frontendSource": [
-      "if test -f frontend/package.json; then cd frontend && npm run type-check --if-present && npm run lint --if-present && npm test --if-present; elif test -f apps/web/package.json; then cd apps/web && npm run type-check --if-present && npm run lint --if-present && npm test --if-present; elif test -f package.json; then npm run type-check --if-present && npm run lint --if-present && npm test --if-present; else echo 'No frontend verify command configured; update .pi/piagent-profile.json'; fi"
+      "if test -f frontend/package.json; then cd frontend; elif test -f apps/web/package.json; then cd apps/web; elif test -f apps/frontend/package.json; then cd apps/frontend; elif test -f packages/web/package.json; then cd packages/web; elif test -f packages/frontend/package.json; then cd packages/frontend; elif test -f client/package.json; then cd client; elif test -f package.json; then :; else echo 'No frontend verify command configured; update .pi/piagent-profile.json'; exit 0; fi; npm run type-check --if-present && npm run lint --if-present && npm test --if-present"
     ],
     "frontendRuntime": [
-      "if test -f frontend/package.json; then cd frontend && npm run test:e2e --if-present; elif test -f apps/web/package.json; then cd apps/web && npm run test:e2e --if-present; elif test -f package.json; then npm run test:e2e --if-present; else echo 'No frontend runtime verify command configured; update .pi/piagent-profile.json'; fi"
+      "if test -f frontend/package.json; then cd frontend; elif test -f apps/web/package.json; then cd apps/web; elif test -f apps/frontend/package.json; then cd apps/frontend; elif test -f packages/web/package.json; then cd packages/web; elif test -f packages/frontend/package.json; then cd packages/frontend; elif test -f client/package.json; then cd client; elif test -f package.json; then :; else echo 'No frontend runtime verify command configured; update .pi/piagent-profile.json'; exit 0; fi; npm run test:e2e --if-present"
     ]
   },
   "mcpCapabilities": [

package/docs/command-reference-vietnamese.md

@@ -419,10 +419,13 @@ 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.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.4` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.6` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
-| 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, npm-global 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). |
+| `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. |
+| `piagent-update --version X.Y.Z` | Update tới đúng một release thay vì latest; dùng cho rollout theo lô hoặc rollback. |
+| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Sequence thủ công tương đương. Thứ tự bắt buộc: `piagent-install` fail nếu Pi host lệch bản pin và không tự cài host. Version pin của từng release nằm 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á dependency risk của host cũ trước khi hạ version. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
 | `piagent-install --stable` | Cài Pi package matching với helper hiện tại bằng resolved commit SHA. |

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.4` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.6` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.1.4` |
+| Registry distribution | `npm:@piagent/platform@1.1.6` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.4` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.6` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.1.4
+pi install git:github.com/Vt-mmm/piagent@v1.1.6
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.1.4` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.1.4`.
+`pi install git:github.com/Vt-mmm/piagent@v1.1.6` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.1.6`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -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.4 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.6 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.1.4`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.1.6`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -156,6 +156,18 @@ Trong Pi:
 
 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.
 
+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`.
+
+Paste xong callback URL mà màn hình đứng im: **bấm Enter**. Ô nhập callback chỉ hiện hint `to cancel`, không hiện `to submit`, nên nó đang chờ submit chứ không đơ.
+
+Đã Enter rồi mà terminal khoá luôn, Esc không thoát được: Pi lưu credential xong mới refresh model catalog từ `pi.dev`, và request đó không có timeout. Firewall hoặc proxy giữ connection im lặng thì `/login` chờ mãi. Credential thực tế đã lưu rồi, nên mở tab mới vẫn dùng được. Login bằng đường này để tránh hẳn:
+
+```bash
+pi --offline
+```
+
+Rồi `/login` → browser → paste → Enter. `--offline` chỉ chặn bước refresh catalog gây treo, OAuth vẫn chạy. Xong thì thoát và mở `pi` bình thường.
+
 ### Chọn model và thinking
 
 Trong Pi:
@@ -269,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.4 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.6 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,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.4` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.4` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.6` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -940,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.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 command -v piagent-install
 ```
 

package/docs/project-adapters.md

@@ -68,6 +68,22 @@ Path policy fields have distinct meanings:
 - `readOnlyPaths`: allow `read`/`grep`/`find`/`ls`, but block `write`/`edit` and shell access.
 - `shellProtectedPaths`: block shell access only. Do not rely on this field to block write/edit; `profile-doctor` and `team-doctor` warn when a path is present only here.
 
+Glob trong các field này neo từ project root, nên `backend/**` chỉ khớp backend nằm ở root. Với monorepo, phải liệt kê đúng vị trí thật (`packages/api/**`, `services/*/**`). Không dùng `**/api/**`: nó khớp luôn `packages/web/src/api/` — thư mục HTTP client của frontend — và biến chính phần được phép sửa thành read-only.
+
+## Monorepo và workspace
+
+Một project = một thư mục mở `pi`. Guard đọc profile tại `<cwd>/.pi/piagent-profile.json` và không đi ngược lên tìm, nên mở `pi` ở thư mục cha chứa nhiều project sẽ bỏ qua profile của từng project con và chạy unprofiled.
+
+Detect FE/BE đọc theo thứ tự:
+
+1. Tên thư mục ở root: `frontend`, `web`, `client`, `ui` cho FE; `backend`, `server`, `api` cho BE.
+2. Cùng các tên đó ở một cấp dưới `apps/`, `packages/`, `services/`.
+3. Package khai báo trong `workspaces` (package.json, cả dạng mảng lẫn `{ "packages": [...] }`) hoặc `pnpm-workspace.yaml` — mỗi package đọc dependency và config của chính nó, nên `packages/storefront` + `packages/gateway` vẫn ra `fullstack` dù tên không gợi ý gì.
+
+Chỉ wildcard ở segment cuối được mở rộng (`packages/*`, `apps/**`); pattern tuyệt đối, pattern có `..`, và pattern loại trừ `!` bị bỏ qua. Số package đọc tối đa 64.
+
+Rule nằm ở `packages/piagent-core/extensions/project-shape.js`. Cả `piagent_profile_options` lẫn `scripts/init-project.sh` cùng gọi file này; trước đây mỗi bên giữ một bản riêng và đã lệch nhau.
+
 ## Built-in adapters
 
 | Profile | Dùng cho | Verify mặc định |
@@ -84,6 +100,11 @@ Path policy fields have distinct meanings:
 | `mobile` | React Native/Flutter | npm test / flutter test nếu tool có |
 | `docs` | Docs portal/manual | markdown diff check + test nếu project có |
 
+`be-readonly-fe` giữ read-only cho backend ở root (`backend`, `server`, `api`), ở một cấp dưới `apps/` và `packages/` (`api`, `server`, `backend`), toàn bộ `services/*`, và mọi `**/migrations/**`. Profile built-in là điểm khởi đầu, không phải danh sách đầy đủ — sửa `readOnlyPaths` **và** `shellProtectedPaths` trong `.pi/piagent-profile.json` cho đúng repo:
+
+- backend đặt tên khác (`apps/gateway`, `packages/core-service`): thêm path vào cả hai field.
+- frontend nằm trong `services/` (ví dụ `services/web`): `services/*/**` sẽ khoá nhầm nó. Thay pattern đó bằng danh sách service backend cụ thể. Triệu chứng là một write bị chặn kèm lý do trỏ tới `readOnlyPaths`, không phải lỗi im lặng.
+
 ## Runtime profile selection
 
 Default UX không bắt buộc chạy bash để set profile. Sau global install, vào project chạy:

package/docs/publishing-for-teams.md

@@ -47,6 +47,8 @@ pi install /path/to/piagent
 - `1.1.2`: đóng TOCTOU của document reader, hash evidence tính trên text đã redact, publish chờ đủ verify matrix.
 - `1.1.3`: command mang secret không còn được dùng làm verify evidence, document reader từ chối FIFO thay vì treo, redact secret ngắn, redirect phải về đúng trang được kiểm.
 - `1.1.4`: nhận diện secret dạng CLI option (`--token`, `--password`, `--api-key`) và Authorization header ở mọi vị trí argument.
+- `1.1.5`: thêm `piagent-update` — một lệnh update cả Pi host, terminal helper và Pi package đúng thứ tự.
+- `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ỗ.
 
 ## Không publish
 

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.4 | Rollout guidance |
+| Surface | Status for v1.1.6 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.4` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.6` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.1.4 (helper package version)
-tag: v1.1.4
+currentRelease: v1.1.6 (helper package version)
+tag: v1.1.6
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,14 +79,26 @@ 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.4
+pi install git:github.com/Vt-mmm/piagent@v1.1.6
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
 
 ## Full platform update
 
-Update the exact supported Pi host first, then the npm-global helper, then let that target helper resolve and install its matching stable Pi package:
+`piagent-update` does the whole sequence in one command:
+
+```bash
+piagent-update --check
+piagent-update --dry-run
+piagent-update --project /path/to/project
+```
+
+It resolves the target helper version and, from that version's published metadata, the exact Pi host that version pins — both before installing anything, so `--check` and `--dry-run` describe a real run. It then installs the host, replaces the helper, verifies that the version now on disk is the one it asked for, and only then runs the new helper's installer for the Pi package. `--version X.Y.Z` targets an exact release instead of latest, `--no-host` and `--no-package` narrow the run, and anything after `--` is passed to `piagent-install`.
+
+Running it from a git checkout is refused rather than replacing that checkout's commands with a published build; update a checkout with `git pull` and `install-global.sh --local`.
+
+The same sequence by hand, which must keep this order because `piagent-install` fails against a host that does not match the version it pins and does not install one itself:
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0

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.4, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.6, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

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.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 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.4
+npm install -g --ignore-scripts @piagent/platform@1.1.6
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -63,7 +63,16 @@ pi install git:github.com/Vt-mmm/piagent
 
 ## Update và rollback cho team
 
-Full update phải đồng bộ exact Pi host trước, sau đó terminal helper và Pi package matching:
+Một lệnh, đúng thứ tự, cho cả ba thành phần:
+
+```bash
+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.6`.
+
+Sequence thủ công vẫn dùng được, và bắt buộc theo thứ tự này — `piagent-install` **fail** nếu Pi host lệch bản pin, nó không tự nâng host:
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
@@ -108,6 +117,8 @@ pi
 
 Credential nằm trong user Pi dir, không commit.
 
+Nếu browser login của OpenAI trông như treo, xem [login provider](operator-manual-vietnamese.md#login-provider). Tóm tắt: paste callback URL xong phải bấm **Enter** (màn hình không nhắc), và nếu sau Enter terminal khoá luôn thì login bằng `pi --offline` một lần. Cả hai là lỗi Pi host `0.82.0`/`0.82.1`, không phải platform.
+
 ## 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.

package/docs-site/index.html

@@ -798,7 +798,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.1.4 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.1.6 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -934,7 +934,7 @@
               <article class="step">
                 <div>
                   <h3>Cài — hai lệnh</h3>
-                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.4</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
+                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.6</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -47,6 +47,7 @@
   "bin": {
     "piagent-setup": "scripts/piagent-cli.mjs",
     "piagent-install": "scripts/piagent-cli.mjs",
+    "piagent-update": "scripts/piagent-cli.mjs",
     "piagent-uninstall": "scripts/piagent-cli.mjs",
     "piagent-init": "scripts/piagent-cli.mjs",
     "piagent-doctor": "scripts/piagent-cli.mjs",

package/packages/piagent-core/capabilities/capability-core.js

@@ -795,7 +795,11 @@ function buildCoreIntegrity(root) {
     "packages/piagent-core/extensions/guard-shell-analysis.ts",
     "packages/piagent-core/extensions/policy-core.js",
     "packages/piagent-core/extensions/redaction-core.js",
-    "packages/piagent-core/extensions/runtime-evidence.js"
+    "packages/piagent-core/extensions/runtime-evidence.js",
+    // project-shape.js picks the profile a project is offered, and the profile is
+    // the document that carries protectedPaths and readOnlyPaths. Steering the
+    // recommendation is a way to choose what the guard will end up enforcing.
+    "packages/piagent-core/extensions/project-shape.js"
   ];
   return files.map((relativePath) => {
     const resolved = resolveRegularFile(root, relativePath, MAX_ARTIFACT_BYTES);

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -39,6 +39,7 @@ import {
   redactForStorage,
   redactSensitiveText
 } from "./redaction-core.js";
+import { detectProfileName } from "./project-shape.js";
 import {
   resolveCapabilityProfileDocument,
   verifyCapabilityLock,
@@ -2636,75 +2637,6 @@ function readAdapterProfiles(extensionDir: string): Array<{ name: string; profil
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-function packageHasAny(cwd: string, pattern: RegExp): boolean {
-  try {
-    return pattern.test(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
-  } catch {
-    return false;
-  }
-}
-
-function detectProfileName(cwd: string, intent?: string): { name: string; reason: string } {
-  const normalizedIntent = intent?.trim().toLowerCase();
-  if (normalizedIntent === "be-readonly-fe") return { name: "be-readonly-fe", reason: "User intent says backend should be read-only while frontend is the write target." };
-  if (normalizedIntent === "frontend-only") return { name: "web-frontend", reason: "User intent says frontend-only." };
-  if (normalizedIntent === "backend-only") return { name: "backend-api", reason: "User intent says backend-only." };
-  if (normalizedIntent === "docs") return { name: "docs", reason: "User intent says docs/docs-only." };
-
-  const hasPackage = fs.existsSync(path.join(cwd, "package.json"));
-  let frontend = false;
-  let backend = false;
-  let data = false;
-  let mobile = false;
-  let infra = false;
-  let docs = false;
-
-  if (fs.existsSync(path.join(cwd, "pubspec.yaml")) || (fs.existsSync(path.join(cwd, "android")) && fs.existsSync(path.join(cwd, "ios")))) mobile = true;
-  if (fs.existsSync(path.join(cwd, "dbt_project.yml")) || fs.existsSync(path.join(cwd, "dvc.yaml")) || fs.existsSync(path.join(cwd, "notebooks")) || fs.existsSync(path.join(cwd, "data"))) data = true;
-  if (fs.existsSync(path.join(cwd, "Dockerfile")) || fs.existsSync(path.join(cwd, "docker-compose.yml")) || fs.existsSync(path.join(cwd, "compose.yml")) || fs.existsSync(path.join(cwd, "compose.yaml")) || fs.existsSync(path.join(cwd, "terraform")) || fs.existsSync(path.join(cwd, "infra")) || fs.existsSync(path.join(cwd, "k8s")) || fs.existsSync(path.join(cwd, "helm"))) infra = true;
-  if (fs.existsSync(path.join(cwd, "docs")) || fs.existsSync(path.join(cwd, "mkdocs.yml")) || fs.existsSync(path.join(cwd, "mint.json")) || fs.existsSync(path.join(cwd, "docusaurus.config.js"))) docs = true;
-
-  if (hasPackage) {
-    if (fs.existsSync(path.join(cwd, "frontend")) || fs.existsSync(path.join(cwd, "apps/web")) || fs.existsSync(path.join(cwd, "apps/frontend"))) frontend = true;
-    if (fs.existsSync(path.join(cwd, "backend")) || fs.existsSync(path.join(cwd, "apps/api")) || fs.existsSync(path.join(cwd, "apps/server"))) backend = true;
-    if (packageHasAny(cwd, /"(next|react|vite|vue|svelte|astro|@angular\/core|remix)"/i)
-      || fs.existsSync(path.join(cwd, "next.config.js"))
-      || fs.existsSync(path.join(cwd, "next.config.mjs"))
-      || fs.existsSync(path.join(cwd, "next.config.ts"))
-      || fs.existsSync(path.join(cwd, "vite.config.js"))
-      || fs.existsSync(path.join(cwd, "vite.config.ts"))
-      || fs.existsSync(path.join(cwd, "src/app"))
-      || fs.existsSync(path.join(cwd, "pages"))
-      || fs.existsSync(path.join(cwd, "public"))) frontend = true;
-    if (packageHasAny(cwd, /"(@nestjs|express|fastify|hono|koa|apollo-server|graphql-yoga|prisma|typeorm|sequelize|drizzle-orm)"/i)
-      || fs.existsSync(path.join(cwd, "nest-cli.json"))
-      || fs.existsSync(path.join(cwd, "prisma"))
-      || fs.existsSync(path.join(cwd, "src/server"))
-      || fs.existsSync(path.join(cwd, "src/api"))) backend = true;
-  }
-
-  if (fs.existsSync(path.join(cwd, "pom.xml")) || fs.existsSync(path.join(cwd, "build.gradle")) || fs.existsSync(path.join(cwd, "build.gradle.kts")) || fs.existsSync(path.join(cwd, "src/main/java")) || fs.existsSync(path.join(cwd, "src/main/kotlin"))) backend = true;
-
-  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) {
-    try {
-      if (/(fastapi|flask|django|litestar|starlite)/i.test(fs.readFileSync(path.join(cwd, "pyproject.toml"), "utf8"))) backend = true;
-    } catch {
-      // ignore unreadable pyproject for recommendation
-    }
-  }
-
-  if (mobile) return { name: "mobile", reason: "Mobile markers found." };
-  if (frontend && backend) return { name: "fullstack", reason: "Frontend and backend markers both found. Pick be-readonly-fe instead if backend must be read-only." };
-  if (frontend) return { name: "web-frontend", reason: "Frontend framework markers found." };
-  if (backend) return { name: "backend-api", reason: "Backend/API markers found." };
-  if (data) return { name: "data", reason: "Data/ETL markers found." };
-  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) return { name: "python", reason: "Python pyproject.toml found." };
-  if (hasPackage && fs.existsSync(path.join(cwd, "tsconfig.json"))) return { name: "node-typescript", reason: "Node TypeScript markers found." };
-  if (infra) return { name: "devops", reason: "Infrastructure markers found." };
-  if (docs) return { name: "docs", reason: "Documentation markers found." };
-  return { name: "generic", reason: "No stronger project markers found." };
-}
-
 function profileDescription(name: string): string {
   const descriptions: Record<string, string> = {
     generic: "Safe baseline for unknown repos.",

package/packages/piagent-core/extensions/project-shape.js

@@ -0,0 +1,285 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// The shape of a repository, in the only terms the profiles care about: is there
+// a frontend, is there a backend, and what else is sitting at the root. Both the
+// runtime recommendation (`piagent_profile_options`) and the shell initialiser
+// (`scripts/init-project.sh`) read it from here. They used to carry separate
+// copies of the same rules, which is how `apps/backend` ended up being invisible
+// to one of them for several releases.
+
+// Directories that name a side of the stack outright. These are matched at the
+// repository root and one level under each workspace root, never at arbitrary
+// depth: `src/api` inside a frontend package is an HTTP client, not a backend.
+const FRONTEND_DIR_NAMES = ["frontend", "web", "client", "ui"];
+const BACKEND_DIR_NAMES = ["backend", "server", "api"];
+const WORKSPACE_ROOTS = ["apps", "packages", "services"];
+
+const FRONTEND_DEPENDENCIES = /"(next|react|vite|vue|svelte|astro|@angular\/core|remix)"/i;
+const BACKEND_DEPENDENCIES = /"(@nestjs|express|fastify|hono|koa|apollo-server|graphql-yoga|prisma|typeorm|sequelize|drizzle-orm)"/i;
+const PYTHON_BACKEND_FRAMEWORKS = /(fastapi|flask|django|litestar|starlite)/i;
+
+const FRONTEND_MARKER_FILES = [
+  "next.config.js",
+  "next.config.mjs",
+  "next.config.ts",
+  "vite.config.js",
+  "vite.config.ts",
+  "src/app",
+  "pages",
+  "public"
+];
+const NODE_BACKEND_MARKER_FILES = ["nest-cli.json", "prisma", "src/server", "src/api"];
+// Markers that identify a backend on their own, with no manifest to lean on.
+const NATIVE_BACKEND_MARKER_FILES = [
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "src/main/java",
+  "src/main/kotlin"
+];
+
+// A workspace file can declare any number of packages. Reading a bounded number
+// of them keeps a repository with hundreds of packages from turning profile
+// recommendation into a directory walk.
+const MAX_WORKSPACE_PACKAGES = 64;
+
+function exists(dir, relative) {
+  try {
+    return fs.existsSync(path.join(dir, relative));
+  } catch {
+    return false;
+  }
+}
+
+// The stack-naming markers are directories. A file called `api` says nothing
+// about a repository having a backend in it.
+function isDirectory(dir, relative) {
+  try {
+    return fs.statSync(path.join(dir, relative)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function readFile(dir, relative) {
+  try {
+    return fs.readFileSync(path.join(dir, relative), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function readJson(dir, relative) {
+  const text = readFile(dir, relative);
+  if (text === undefined) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function stripQuotes(value) {
+  return value.trim().replace(/^['"]/, "").replace(/['"]$/, "").trim();
+}
+
+// npm and yarn put the globs in package.json, pnpm puts them in its own file.
+// Both are read: a repository is free to carry either, and some carry both.
+function readWorkspacePatterns(cwd) {
+  const patterns = [];
+
+  const declared = readJson(cwd, "package.json")?.workspaces;
+  if (Array.isArray(declared)) {
+    patterns.push(...declared);
+  } else if (Array.isArray(declared?.packages)) {
+    patterns.push(...declared.packages);
+  }
+
+  patterns.push(...readPnpmWorkspacePatterns(cwd));
+  return patterns.filter((pattern) => typeof pattern === "string");
+}
+
+// A three-line YAML reader rather than a YAML dependency: this package ships
+// with no runtime dependencies, and the shape being read is a single list of
+// strings under one key.
+function readPnpmWorkspacePatterns(cwd) {
+  const text = readFile(cwd, "pnpm-workspace.yaml") ?? readFile(cwd, "pnpm-workspace.yml");
+  if (text === undefined) return [];
+
+  const patterns = [];
+  let insidePackages = false;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/#.*$/, "");
+    if (/^packages\s*:/.test(line)) {
+      insidePackages = true;
+      continue;
+    }
+    if (!insidePackages) continue;
+
+    const item = line.match(/^\s+-\s*(.+?)\s*$/);
+    if (item) {
+      patterns.push(stripQuotes(item[1]));
+      continue;
+    }
+    // A blank line stays inside the list; anything else starts the next key.
+    if (line.trim().length > 0) break;
+  }
+  return patterns;
+}
+
+function expandWorkspacePattern(cwd, pattern) {
+  const normalized = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+  // `!` excludes rather than includes, and neither an absolute path nor one that
+  // climbs out of the repository is a workspace of this repository.
+  if (!normalized || normalized.startsWith("!") || normalized.startsWith("/")) return [];
+
+  const segments = normalized.split("/").filter((segment) => segment && segment !== ".");
+  if (segments.length === 0 || segments.includes("..")) return [];
+
+  const wildcardAt = segments.findIndex((segment) => segment.includes("*"));
+  if (wildcardAt === -1) return [segments.join("/")];
+  // Only a trailing wildcard is expanded. `packages/*` and `apps/**` are what
+  // workspace files actually declare; anything deeper is left to the directory
+  // and dependency markers instead of growing a glob engine in here.
+  if (wildcardAt !== segments.length - 1) return [];
+
+  const base = segments.slice(0, wildcardAt).join("/");
+  let entries;
+  try {
+    entries = fs.readdirSync(base ? path.join(cwd, base) : cwd, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => (base ? `${base}/${entry.name}` : entry.name));
+}
+
+export function readWorkspacePackageDirs(cwd) {
+  const found = [];
+  const seen = new Set();
+  for (const pattern of readWorkspacePatterns(cwd)) {
+    for (const relative of expandWorkspacePattern(cwd, pattern)) {
+      if (seen.has(relative)) continue;
+      if (!exists(cwd, relative)) continue;
+      seen.add(relative);
+      found.push(relative);
+      if (found.length >= MAX_WORKSPACE_PACKAGES) return found;
+    }
+  }
+  return found;
+}
+
+// What one directory says about itself, from its manifest and its own layout.
+// Applied to the repository root and to every declared workspace package, so a
+// pnpm monorepo whose packages are named `web` and `api` is read the same way a
+// single-package repository is.
+function directorySignals(dir) {
+  const manifest = readFile(dir, "package.json");
+  let frontend = false;
+  let backend = false;
+
+  if (manifest !== undefined) {
+    frontend = FRONTEND_DEPENDENCIES.test(manifest);
+    backend = BACKEND_DEPENDENCIES.test(manifest);
+    // Node layout markers only mean something next to a manifest. `public/` and
+    // `pages/` are ordinary directory names in repositories that have nothing to
+    // do with a web framework.
+    if (!frontend) frontend = FRONTEND_MARKER_FILES.some((marker) => exists(dir, marker));
+    if (!backend) backend = NODE_BACKEND_MARKER_FILES.some((marker) => exists(dir, marker));
+  }
+
+  if (!backend) backend = NATIVE_BACKEND_MARKER_FILES.some((marker) => exists(dir, marker));
+
+  const pyproject = readFile(dir, "pyproject.toml");
+  if (pyproject !== undefined && PYTHON_BACKEND_FRAMEWORKS.test(pyproject)) backend = true;
+
+  return { frontend, backend };
+}
+
+function shapeFromDirName(name) {
+  const normalized = name.toLowerCase();
+  if (FRONTEND_DIR_NAMES.includes(normalized)) return "frontend";
+  if (BACKEND_DIR_NAMES.includes(normalized)) return "backend";
+  return undefined;
+}
+
+export function detectProjectShape(cwd) {
+  const hasPackage = exists(cwd, "package.json");
+  const shape = {
+    hasPackage,
+    frontend: false,
+    backend: false,
+    data: false,
+    mobile: false,
+    infra: false,
+    docs: false,
+    workspacePackages: []
+  };
+
+  if (exists(cwd, "pubspec.yaml") || (exists(cwd, "android") && exists(cwd, "ios"))) shape.mobile = true;
+  if (exists(cwd, "dbt_project.yml") || exists(cwd, "dvc.yaml") || exists(cwd, "notebooks") || exists(cwd, "data")) {
+    shape.data = true;
+  }
+  if (exists(cwd, "Dockerfile") || exists(cwd, "docker-compose.yml") || exists(cwd, "compose.yml")
+    || exists(cwd, "compose.yaml") || exists(cwd, "terraform") || exists(cwd, "infra")
+    || exists(cwd, "k8s") || exists(cwd, "helm")) {
+    shape.infra = true;
+  }
+  if (exists(cwd, "docs") || exists(cwd, "mkdocs.yml") || exists(cwd, "mint.json") || exists(cwd, "docusaurus.config.js")) {
+    shape.docs = true;
+  }
+
+  // Directory names are read whether or not the root carries a package.json.
+  // A Django and React repository has `frontend/` and `backend/` and no root
+  // manifest at all; gating this on package.json used to hide both sides of it.
+  for (const name of [...FRONTEND_DIR_NAMES, ...BACKEND_DIR_NAMES]) {
+    const side = shapeFromDirName(name);
+    if (isDirectory(cwd, name)) shape[side] = true;
+    for (const root of WORKSPACE_ROOTS) {
+      if (isDirectory(cwd, `${root}/${name}`)) shape[side] = true;
+    }
+  }
+
+  const rootSignals = directorySignals(cwd);
+  if (rootSignals.frontend) shape.frontend = true;
+  if (rootSignals.backend) shape.backend = true;
+
+  shape.workspacePackages = readWorkspacePackageDirs(cwd);
+  for (const relative of shape.workspacePackages) {
+    const side = shapeFromDirName(path.posix.basename(relative));
+    if (side) shape[side] = true;
+
+    const signals = directorySignals(path.join(cwd, relative));
+    if (signals.frontend) shape.frontend = true;
+    if (signals.backend) shape.backend = true;
+  }
+
+  return shape;
+}
+
+export function detectProfileName(cwd, intent) {
+  const normalizedIntent = typeof intent === "string" ? intent.trim().toLowerCase() : "";
+  if (normalizedIntent === "be-readonly-fe") {
+    return { name: "be-readonly-fe", reason: "User intent says backend should be read-only while frontend is the write target." };
+  }
+  if (normalizedIntent === "frontend-only") return { name: "web-frontend", reason: "User intent says frontend-only." };
+  if (normalizedIntent === "backend-only") return { name: "backend-api", reason: "User intent says backend-only." };
+  if (normalizedIntent === "docs") return { name: "docs", reason: "User intent says docs/docs-only." };
+
+  const shape = detectProjectShape(cwd);
+
+  if (shape.mobile) return { name: "mobile", reason: "Mobile markers found." };
+  if (shape.frontend && shape.backend) {
+    return { name: "fullstack", reason: "Frontend and backend markers both found. Pick be-readonly-fe instead if backend must be read-only." };
+  }
+  if (shape.frontend) return { name: "web-frontend", reason: "Frontend framework markers found." };
+  if (shape.backend) return { name: "backend-api", reason: "Backend/API markers found." };
+  if (shape.data) return { name: "data", reason: "Data/ETL markers found." };
+  if (exists(cwd, "pyproject.toml")) return { name: "python", reason: "Python pyproject.toml found." };
+  if (shape.hasPackage && exists(cwd, "tsconfig.json")) return { name: "node-typescript", reason: "Node TypeScript markers found." };
+  if (shape.infra) return { name: "devops", reason: "Infrastructure markers found." };
+  if (shape.docs) return { name: "docs", reason: "Documentation markers found." };
+  return { name: "generic", reason: "No stronger project markers found." };
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "type": "module",
   "private": true,
   "license": "MIT",

package/scripts/init-project.sh

@@ -102,97 +102,20 @@ fi
 
 PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
 
-package_has_any() {
-  local project="$1"
-  local pattern="$2"
-  [[ -f "$project/package.json" ]] && grep -Eiq "$pattern" "$project/package.json"
-}
-
+# Profile detection lives in packages/piagent-core/extensions/project-shape.js so
+# that this script and the runtime `piagent_profile_options` tool recommend the
+# same profile. They used to hold separate copies of the rules and drifted apart.
 detect_profile() {
   local project="$1"
-  local has_package=false
-  local frontend=false
-  local backend=false
-  local data=false
-  local mobile=false
-  local devops=false
-  local infra=false
-  local docs=false
-
-  [[ -f "$project/package.json" ]] && has_package=true
-
-  if [[ -f "$project/pubspec.yaml" ]] || { [[ -d "$project/android" ]] && [[ -d "$project/ios" ]]; }; then
-    mobile=true
-  fi
-
-  if [[ -f "$project/dbt_project.yml" ]] || [[ -f "$project/dvc.yaml" ]] || [[ -d "$project/notebooks" ]] || [[ -d "$project/data" ]]; then
-    data=true
-  fi
-
-  if [[ -f "$project/Dockerfile" ]] || [[ -f "$project/docker-compose.yml" ]] || [[ -f "$project/compose.yml" ]] || [[ -f "$project/compose.yaml" ]] || [[ -d "$project/terraform" ]] || [[ -d "$project/infra" ]] || [[ -d "$project/k8s" ]] || [[ -d "$project/helm" ]]; then
-    infra=true
-    devops=true
-  elif [[ -d "$project/.github/workflows" ]]; then
-    devops=true
-  fi
-
-  if [[ -d "$project/docs" ]] || [[ -f "$project/mkdocs.yml" ]] || [[ -f "$project/mint.json" ]] || [[ -f "$project/docusaurus.config.js" ]]; then
-    docs=true
-  fi
-
-  if [[ "$has_package" == true ]]; then
-    if [[ -d "$project/frontend" ]] || [[ -d "$project/apps/web" ]] || [[ -d "$project/apps/frontend" ]]; then
-      frontend=true
-    fi
-
-    if [[ -d "$project/backend" ]] || [[ -d "$project/apps/api" ]] || [[ -d "$project/apps/server" ]]; then
-      backend=true
-    fi
-
-    if package_has_any "$project" '"(next|react|vite|vue|svelte|astro|@angular/core|remix)"' \
-      || [[ -f "$project/next.config.js" ]] || [[ -f "$project/next.config.mjs" ]] || [[ -f "$project/next.config.ts" ]] \
-      || [[ -f "$project/vite.config.js" ]] || [[ -f "$project/vite.config.ts" ]] \
-      || [[ -d "$project/src/app" ]] || [[ -d "$project/pages" ]] || [[ -d "$project/public" ]]; then
-      frontend=true
-    fi
-
-    if package_has_any "$project" '"(@nestjs|express|fastify|hono|koa|apollo-server|graphql-yoga|prisma|typeorm|sequelize|drizzle-orm)"' \
-      || [[ -f "$project/nest-cli.json" ]] || [[ -d "$project/prisma" ]] || [[ -d "$project/src/server" ]] || [[ -d "$project/src/api" ]]; then
-      backend=true
-    fi
-  fi
-
-  if [[ -f "$project/pom.xml" ]] || [[ -f "$project/build.gradle" ]] || [[ -f "$project/build.gradle.kts" ]] || [[ -d "$project/src/main/java" ]] || [[ -d "$project/src/main/kotlin" ]]; then
-    backend=true
-  fi
-
-  if [[ -f "$project/pyproject.toml" ]] && grep -Eiq "(fastapi|flask|django|litestar|starlite)" "$project/pyproject.toml"; then
-    backend=true
-  fi
-
-  if [[ "$mobile" == true ]]; then
-    printf '%s\n' "mobile"
-  elif [[ "$frontend" == true && "$backend" == true ]]; then
-    printf '%s\n' "fullstack"
-  elif [[ "$frontend" == true ]]; then
-    printf '%s\n' "web-frontend"
-  elif [[ "$backend" == true ]]; then
-    printf '%s\n' "backend-api"
-  elif [[ "$data" == true ]]; then
-    printf '%s\n' "data"
-  elif [[ -f "$project/pyproject.toml" ]]; then
-    printf '%s\n' "python"
-  elif [[ "$has_package" == true && -f "$project/tsconfig.json" ]]; then
-    printf '%s\n' "node-typescript"
-  elif [[ "$infra" == true ]]; then
-    printf '%s\n' "devops"
-  elif [[ "$docs" == true ]]; then
-    printf '%s\n' "docs"
-  elif [[ "$devops" == true ]]; then
-    printf '%s\n' "devops"
-  else
-    printf '%s\n' "generic"
-  fi
+  node --input-type=module - "$PLATFORM_ROOT" "$project" <<'NODE'
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [platformRoot, project] = process.argv.slice(2);
+const modulePath = path.join(platformRoot, "packages/piagent-core/extensions/project-shape.js");
+const { detectProfileName } = await import(pathToFileURL(modulePath).href);
+process.stdout.write(`${detectProfileName(project).name}\n`);
+NODE
 }
 
 resolve_profile_path() {

package/scripts/install-global.sh

@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.1.4 --resolve-tag
+  scripts/install-global.sh --version v1.1.6 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -127,7 +127,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.1.4 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.6 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -135,7 +135,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.4 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.6 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;

package/scripts/piagent-cli.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 const scriptByCommand = {
   "piagent-setup": "scripts/setup.sh",
   "piagent-install": "scripts/install-global.sh",
+  "piagent-update": "scripts/update-global.mjs",
   "piagent-uninstall": "scripts/uninstall-global.sh",
   "piagent-init": "scripts/init-project.sh",
   "piagent-doctor": "scripts/team-doctor.sh",

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.1.4 support matrix."
+    note: "This runtime is outside the documented v1.1.6 support matrix."
   };
 }
 

package/scripts/update-global.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// One command that moves a machine from one release to the next.
+//
+// A release is three independently versioned things: the Pi host, this npm-global
+// terminal helper, and the Pi package the helper installs. They have to move in
+// that order, because `piagent-install` refuses to run against a host that does
+// not match the version its own package.json pins. Doing it by hand means three
+// commands and one ordering rule, and getting the order wrong fails late.
+//
+// The awkward part is that the helper is the program running this file, so it has
+// to replace itself. Rather than re-exec a half-replaced process, every version
+// this run needs is resolved from the registry *before* anything is installed:
+// the target helper version and, from that version's metadata, the host version it
+// will demand. The plan is therefore complete and printable before the first
+// mutation, `--dry-run` shows exactly what a real run would do, and after the
+// helper is replaced the run only has to confirm that what landed on disk is what
+// it asked for.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const HELPER_PACKAGE = "@piagent/platform";
+const HOST_PACKAGE = "@earendil-works/pi-coding-agent";
+const EXIT_USAGE = 2;
+
+const platformRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function usage() {
+  return `Usage:
+  piagent-update [options]
+
+Updates the Pi host, this terminal helper, and the Pi package together, in the
+order a release requires.
+
+Options:
+  --check                 Report current and available versions, change nothing
+  --dry-run               Print every command that would run, change nothing
+  --version <x.y.z>       Update to an exact helper version instead of latest
+  --force                 Reinstall even when already on the target version
+  --project <path>        Run the team doctor against this project afterwards
+  --no-host               Do not touch the Pi host
+  --no-package            Do not reinstall the Pi package
+  -h, --help              Show this help
+
+Anything after -- is passed through to piagent-install, for example:
+  piagent-update -- --no-mcp
+`;
+}
+
+function fail(message, code = 1) {
+  console.error(`FAIL: ${message}`);
+  process.exit(code);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function isReleaseVersion(value) {
+  return typeof value === "string" && /^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$/.test(value);
+}
+
+// "v1.2.3" and "1.2.3" both name the same release everywhere else in this
+// repository, so accept either and normalise once.
+function normalizeVersion(value) {
+  return typeof value === "string" && value.startsWith("v") ? value.slice(1) : value;
+}
+
+function parseArguments(argv) {
+  const options = {
+    check: false,
+    dryRun: false,
+    force: false,
+    version: undefined,
+    project: undefined,
+    host: true,
+    package: true,
+    passthrough: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") {
+      options.passthrough = argv.slice(index + 1);
+      break;
+    }
+    switch (argument) {
+      case "-h":
+      case "--help":
+        process.stdout.write(usage());
+        process.exit(0);
+        break;
+      case "--check":
+        options.check = true;
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "--no-host":
+        options.host = false;
+        break;
+      case "--no-package":
+        options.package = false;
+        break;
+      case "--version": {
+        const value = normalizeVersion(argv[index += 1]);
+        if (!isReleaseVersion(value)) fail(`--version needs an exact release such as 1.1.4, got ${argv[index] ?? "nothing"}`, EXIT_USAGE);
+        options.version = value;
+        break;
+      }
+      case "--project": {
+        const value = argv[index += 1];
+        if (!value) fail("--project needs a path", EXIT_USAGE);
+        options.project = value;
+        break;
+      }
+      default:
+        fail(`unknown option: ${argument}\n\n${usage()}`, EXIT_USAGE);
+    }
+  }
+
+  return options;
+}
+
+function run(command, args, { capture = false } = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit"
+  });
+  if (result.error) return { ok: false, stdout: "", stderr: String(result.error.message ?? result.error) };
+  return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+function npmView(specifier, field) {
+  const result = run("npm", ["view", specifier, field, "--json"], { capture: true });
+  if (!result.ok) return undefined;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return undefined;
+  }
+}
+
+function installedHostVersion() {
+  const result = run("pi", ["--version"], { capture: true });
+  if (!result.ok) return undefined;
+  const match = /([0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?)/.exec(result.stdout);
+  return match ? match[1] : undefined;
+}
+
+// The helper installs itself from the registry, so a run started from a git
+// checkout would replace the checkout's own commands with a published build and
+// leave the operator somewhere they did not ask to be.
+function runningFromGlobalInstall() {
+  return platformRoot.split(path.sep).includes("node_modules");
+}
+
+function describeStep(dryRun, command, args) {
+  console.log(`${dryRun ? "DRY RUN:" : "run:"} ${command} ${args.join(" ")}`);
+}
+
+function main() {
+  const options = parseArguments(process.argv.slice(2));
+
+  const manifest = readJson(path.join(platformRoot, "package.json"));
+  if (!manifest?.version) fail(`cannot read the helper package at ${platformRoot}`);
+  const currentHelper = manifest.version;
+  const currentHost = installedHostVersion();
+
+  const targetHelper = options.version ?? npmView(HELPER_PACKAGE, "version");
+  if (!isReleaseVersion(targetHelper)) {
+    fail(`cannot resolve a release for ${HELPER_PACKAGE}. Check network access to the npm registry, or pass --version.`);
+  }
+
+  // The host requirement belongs to the version being installed, not the one
+  // running, so it is read from the target's published metadata.
+  const targetPeers = npmView(`${HELPER_PACKAGE}@${targetHelper}`, "peerDependencies");
+  const targetHost = targetPeers?.[HOST_PACKAGE];
+  if (!isReleaseVersion(targetHost)) {
+    fail(`${HELPER_PACKAGE}@${targetHelper} does not pin an exact ${HOST_PACKAGE} version, so the host cannot be updated safely.`);
+  }
+
+  const helperNeedsChange = options.force || currentHelper !== targetHelper;
+  const hostNeedsChange = options.host && (options.force || currentHost !== targetHost);
+
+  console.log("Pi Agent Platform update");
+  console.log(`  helper:  ${currentHelper} -> ${targetHelper}${helperNeedsChange ? "" : " (already current)"}`);
+  console.log(`  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
+  console.log(`  package: reinstalled from v${targetHelper} as a resolved commit${options.package ? "" : " (skipped)"}`);
+
+  if (options.check) {
+    const pending = [helperNeedsChange && "helper", hostNeedsChange && "host"].filter(Boolean);
+    console.log(pending.length ? `\nUpdate available: ${pending.join(", ")}.` : "\nEverything is on the target release.");
+    return;
+  }
+
+  if (!helperNeedsChange && !hostNeedsChange && !options.package) {
+    console.log("\nNothing to do.");
+    return;
+  }
+
+  if (!options.dryRun && !runningFromGlobalInstall()) {
+    fail(`this command updates the npm-global helper, but it is running from ${platformRoot}.\n`
+      + "From a checkout, update with git and install from it:\n"
+      + `  git -C ${platformRoot} pull\n`
+      + `  bash ${path.join(platformRoot, "scripts/install-global.sh")} --local`);
+  }
+
+  // Host first: piagent-install refuses to run against a host that does not match
+  // the version its package.json pins, so a helper installed ahead of the host
+  // would fail on its very next step.
+  if (hostNeedsChange) {
+    const args = ["install", "-g", "--ignore-scripts", `${HOST_PACKAGE}@${targetHost}`];
+    describeStep(options.dryRun, "npm", args);
+    if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);
+  }
+
+  if (helperNeedsChange) {
+    const args = ["install", "-g", "--ignore-scripts", `${HELPER_PACKAGE}@${targetHelper}`];
+    describeStep(options.dryRun, "npm", args);
+    if (!options.dryRun) {
+      if (!run("npm", args).ok) fail(`could not install ${HELPER_PACKAGE}@${targetHelper}`);
+      // The helper has just replaced itself on disk. Everything after this point
+      // runs the newly installed scripts, so confirm they are the ones asked for
+      // rather than trusting that npm did what it said.
+      const landed = readJson(path.join(platformRoot, "package.json"))?.version;
+      if (landed !== targetHelper) {
+        fail(`installed ${HELPER_PACKAGE}@${targetHelper} but ${platformRoot} reports ${landed ?? "nothing"}. `
+          + "The Pi package was left untouched; rerun once the helper is correct.");
+      }
+    }
+  }
+
+  if (options.package) {
+    const installer = path.join(platformRoot, "scripts/install-global.sh");
+    if (!options.dryRun && !fs.existsSync(installer)) {
+      fail(`the updated helper has no installer at ${installer}`);
+    }
+    const args = [installer, "--stable", ...options.passthrough];
+    describeStep(options.dryRun, "bash", args);
+    if (!options.dryRun && !run("bash", args).ok) fail("the Pi package install did not complete");
+  }
+
+  if (options.project) {
+    const doctor = path.join(platformRoot, "scripts/team-doctor.sh");
+    const args = [doctor, options.project, "--strict-share"];
+    describeStep(options.dryRun, "bash", args);
+    if (!options.dryRun && !run("bash", args).ok) fail("the team doctor reported a problem");
+  }
+
+  console.log(options.dryRun
+    ? `\nDRY RUN: nothing was installed. Rerun without --dry-run to apply v${targetHelper}.`
+    : `\nPASS: updated to v${targetHelper}.`);
+}
+
+main();