@piagent/platform 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.0.1 - 2026-07-25
+
+Documentation release. v1.0.0 reached the npm registry but no document told anyone it was there, so every install instruction still pointed at the Git source.
+
+### Changed
+
+- The terminal helper now installs from the registry: `npm install -g --ignore-scripts @piagent/platform@1.0.1`. This replaces the `github:Vt-mmm/piagent#vX.Y.Z` form in the README, the docs site, and every install, update, and rollback flow. Installing from Git still works and produces the same files; the registry path additionally carries a provenance attestation npm can verify.
+- Added an `npm` release channel with a real source, and narrowed `enterprise-npm` to what it actually describes: a fork published under a different scope.
+- Recorded why `stable` still resolves the Pi package to a commit SHA rather than an npm version. Tag-to-SHA resolution is checked against `PIAGENT_EXPECTED_RELEASE_COMMIT`, and a registry version range cannot express that check, so pointing `stable` at npm would remove it rather than replace it.
+- Aligned `repository.url` in both manifests with the form npm stores. Publishing rewrote the field and warned, which left the manifest in the repository disagreeing with the manifest on the registry.
+
 ## v1.0.0 - 2026-07-25
 
 Breaking release. The `company` namespace is replaced by `piagent` with no alias layer, and `apiVersion` becomes a stable contract. Existing projects convert their local state with one migration command; both names never work at once.

package/README.md

@@ -114,7 +114,7 @@ Node.js `>=22.19.0` and Pi Coding Agent `0.81.1` are required. Pi Coding Agent i
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -124,7 +124,7 @@ The npm command installs the `piagent-*` terminal helpers. `piagent-install --st
 If you only need to install the Pi package and do not need the `piagent-*` terminal commands, pin the current release tag or a reviewed commit directly:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.0
+pi install git:github.com/Vt-mmm/piagent@v1.0.1
 ```
 
 From a checked-out platform repo, the same helper is available as a script:
@@ -138,7 +138,7 @@ For a full update, update the exact Pi host first, then the npm-global helper, t
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -423,7 +423,7 @@ Most projects do not need shell init. Use this only when you want to pre-create
 ```bash
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -538,7 +538,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.0.0` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.0.1` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -380,10 +380,10 @@ 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.81.1` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.0` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.0.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.0.1` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
-| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, npm-global helper và Pi package. v1.0.0 yêu cầu Pi `0.81.1`. |
+| 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. v1.0.1 yêu cầu Pi `0.81.1`. |
 | 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,10 @@ 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.0.0` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.0.1` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Enterprise npm | `npm:@your-scope/platform@x.y.z` |
+| Registry distribution | `npm:@piagent/platform@1.0.1` |
+| Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
 Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commit cho `.pi/settings.json` trong project nghiêm túc để tránh workflow đổi bất ngờ giữa các developer.
@@ -25,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.0.0` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.0.1` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -52,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.0.0
+pi install git:github.com/Vt-mmm/piagent@v1.0.1
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -64,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.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.0.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 github:Vt-mmm/piagent#v1.0.0`.
+`pi install git:github.com/Vt-mmm/piagent@v1.0.1` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.0.1`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -102,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.0.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -175,7 +176,7 @@ Full platform update phải đồng bộ Pi host, npm-global helper và Pi packa
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share
@@ -186,7 +187,7 @@ Full rollback dùng cùng flow với target trước đó. Lấy exact host vers
 ```bash
 TARGET_PI_VERSION=x.y.z
 npm install -g --ignore-scripts "@earendil-works/pi-coding-agent@$TARGET_PI_VERSION"
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vPREVIOUS
+npm install -g --ignore-scripts @piagent/platform@PREVIOUS
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share

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.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 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.0.0`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.0.1`. 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:
 
@@ -38,7 +38,7 @@ Full update phải đồng bộ exact Pi host trước, rồi npm-global helper
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -269,7 +269,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.0.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -842,10 +842,10 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.0` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.0.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.0.1` | 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 github:Vt-mmm/piagent#vX.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. v1.0.0 yêu cầu Pi `0.81.1`. |
+| 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. v1.0.1 yêu cầu Pi `0.81.1`. |
 | 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. |
 | `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
 | `piagent-install --stable` | Apply Pi package matching với helper hiện tại bằng resolved commit SHA. |
@@ -936,7 +936,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 github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 command -v piagent-install
 ```
 

package/docs/publishing-for-teams.md

@@ -42,7 +42,7 @@ pi install /path/to/piagent
 
 - `0.1.x`: local/internal pilot.
 - `0.2.x`: có guard ổn định và docs team.
-- `1.0.0`: đủ security review, MCP registry, adapter schema versioned.
+- `1.0.1`: đủ security review, MCP registry, adapter schema versioned.
 
 ## Không publish
 

package/docs/quickstart-vietnamese.md

@@ -31,17 +31,17 @@ Node.js phải từ `22.19.0` trở lên và Pi Coding Agent phải là `0.81.1`
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Lệnh trên cài Pi CLI, cài terminal command `piagent-*`, rồi install Pi Agent Platform bằng stable release đã resolve tag thành commit SHA. Trong output installer, `currentRelease` là version của terminal helper đang chạy. `v1.0.0` là release hiện tại của docs này.
+Lệnh trên cài Pi CLI, cài terminal command `piagent-*`, rồi install Pi Agent Platform bằng stable release đã resolve tag thành commit SHA. Trong output installer, `currentRelease` là version của terminal helper đang chạy. `v1.0.1` là release hiện tại của docs này.
 
 Nếu chỉ cần cài package vào Pi và không cần terminal command helper:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.0.0
+pi install git:github.com/Vt-mmm/piagent@v1.0.1
 ```
 
 Nếu đang ở source checkout của platform, có thể preview và áp stable bằng helper:
@@ -57,7 +57,7 @@ Khi update toàn bộ platform, cập nhật exact Pi host trước rồi dùng
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -218,7 +218,7 @@ Nếu chưa có profile/tech stack, dùng select-style flow để tránh agent t
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -241,7 +241,7 @@ Script bash chỉ dùng khi muốn preseed config vào repo:
 ```bash
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.0.0 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```

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.81.1`. 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.0.0 | Rollout guidance |
+| Surface | Status for v1.0.1 | 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. |
@@ -24,7 +24,7 @@ All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.81
 | Component | Installed by | Provides |
 |---|---|---|
 | Pi host runtime | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@<exact-version>` | The compatible `pi` executable. |
-| Terminal helper | `npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z` | `piagent-*` commands on `PATH`. |
+| Terminal helper | `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` | `piagent-*` commands on `PATH`. |
 | Pi package | `piagent-install`, or `pi install ...` | Extensions, prompts, skills, and subagents loaded by Pi. |
 
 These three components are versioned independently. A full install, update, or rollback must use the exact Pi host declared by the target release, then install the target terminal helper, then let that helper install its matching Pi package. `piagent-install` changes only the Pi package; it does not replace the Pi host or the npm-global terminal helper currently executing. In installer output, `currentRelease` is the terminal helper package version.
@@ -33,14 +33,17 @@ 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.0.0` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.0.1` | 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. |
-| `enterprise-npm` | `npm:@your-scope/platform@x.y.z` | Fixed | Private registry distribution when available. |
+| `npm` | `npm:@piagent/platform@x.y.z` | Fixed | Registry distribution. Use when the machine has no Git access to this repository. |
+| `enterprise-npm` | `npm:@your-scope/platform@x.y.z` | Fixed | Private registry distribution when a fork is published under another scope. |
 
 `--stable` reads the helper package version from its own `package.json`, resolves that release tag through GitHub, and installs the resulting commit SHA. If the tag cannot be resolved, install fails closed. Release CI additionally sets `PIAGENT_EXPECTED_RELEASE_COMMIT`; the installer then rejects a tag that resolves anywhere except the commit being verified.
 
+The terminal helper installs from the registry while `stable` still resolves the Pi package to a commit SHA. That difference is deliberate. The helper is a published tarball whose provenance attestation is what ties it back to a commit, and npm verifies that. The Pi package instead relies on tag-to-SHA resolution checked against `PIAGENT_EXPECTED_RELEASE_COMMIT`, which is a separate chain that a registry version range cannot express. Pointing `stable` at an npm version would drop that check rather than replace it, so the `npm` channel exists for machines without Git access to this repository, not as the default.
+
 Exactly one CLI package selector is accepted: `--package-source`, `--channel`, `--stable`, `--dev`, `--local`, `--version`, or `--tag`. The first CLI selector may replace environment defaults; a second CLI selector is rejected before any install command is printed or executed.
 
 ## First install — full platform
@@ -50,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.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -58,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.0.0 (helper package version)
-tag: v1.0.0
+currentRelease: v1.0.1 (helper package version)
+tag: v1.0.1
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -76,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.0.0
+pi install git:github.com/Vt-mmm/piagent@v1.0.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.
@@ -87,7 +90,7 @@ Update the exact supported Pi host first, then the npm-global helper, then let t
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share
@@ -120,7 +123,7 @@ Rollback the host, helper, and Pi package together. Determine the exact host ver
 ```bash
 TARGET_PI_VERSION=x.y.z  # replace from vPREVIOUS release policy before execution
 npm install -g --ignore-scripts "@earendil-works/pi-coding-agent@$TARGET_PI_VERSION"
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vPREVIOUS
+npm install -g --ignore-scripts @piagent/platform@PREVIOUS
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share
@@ -154,6 +157,24 @@ Before broad team access, a repository administrator must enable these external
 
 Verify these settings in GitHub **Settings → Rules** and **Settings → Code security and analysis**. Treat any missing control as an explicit rollout blocker, not as a passing source-code gate. Repository rules also close the remaining mutability risk of bootstrap-by-tag; tag-to-SHA resolution inside `piagent-install` alone cannot protect the helper package before it starts.
 
+### Required npm publishing controls
+
+The publish workflow authenticates with the `NPM_TOKEN` repository secret. That token needs three things, and read-and-write access alone is not enough:
+
+1. Read and write access to the `@piagent` scope.
+2. **Bypass two-factor authentication** enabled on the token. When the npm account requires 2FA for publishing, the registry rejects the upload with `E403 ... two-factor authentication or granular access token with bypass 2fa enabled is required`. CI cannot answer a 2FA prompt, so this is the only way a workflow can publish.
+3. An expiry date the maintainer tracks. An expired token fails as an authentication error that does not say the token expired.
+
+The workflow reaches the registry only at its final step, so every gate can pass and the release can still stop there. A failed upload publishes nothing, but the provenance attestation is signed and written to the public transparency log first, so a failed attempt still leaves a public record of the repository, commit, and workflow.
+
+Fix the token, then re-run the failed job on the same tag so the publish step still sees a tag ref:
+
+```bash
+gh run rerun <run-id> --failed
+```
+
+Re-running the workflow from a branch instead skips publishing, because the publish step requires a tag ref.
+
 1. Update package versions, `CHANGELOG.md`, install examples, and docs metadata on a release-candidate branch.
 2. Verify the exact release-candidate source:
 

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.0.0, 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.0.1, 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.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable
 cd /path/to/project
 pi
@@ -41,7 +41,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.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -66,7 +66,7 @@ Full update phải đồng bộ exact Pi host trước, sau đó terminal helper
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable
 piagent-doctor /path/to/project --strict-share

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.0.0 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.0.1 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>Chuẩn bị runtime</h3>
-                  <p>Dùng Node.js 22.19.0 trở lên và Pi Coding Agent <span class="inline-code">0.81.1</span>. Pi Agent Platform <span class="inline-code">v1.0.0</span> đang pin compatibility với runtime này và công bố support matrix theo OS/CPU riêng cho platform helper.</p>
+                  <p>Dùng Node.js 22.19.0 trở lên và Pi Coding Agent <span class="inline-code">0.81.1</span>. Pi Agent Platform <span class="inline-code">v1.0.1</span> đang pin compatibility với runtime này và công bố support matrix theo OS/CPU riêng cho platform helper.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>
@@ -976,14 +976,14 @@ pi --version</code></pre>
                   <h3>Cài Pi Agent Platform có pin</h3>
                   <p>Team nên cài npm-global helper trước, rồi dùng helper đó resolve stable tag thành commit SHA và cài Pi package matching. Trong output, <span class="inline-code">currentRelease</span> là version của terminal helper đang chạy. Direct Pi install chỉ dùng khi không cần command <span class="inline-code">piagent-*</span>.</p>
                   <div class="command-card">
-                    <header><span>Stable helper install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
-                    <pre><code>npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+                    <header><span>Stable helper install</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @piagent/platform@1.0.1&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+                    <pre><code>npm install -g --ignore-scripts @piagent/platform@1.0.1
 piagent-install --stable --dry-run
 piagent-install --stable</code></pre>
                   </div>
                   <div class="command-card">
-                    <header><span>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.0">Lấy lệnh</button></header>
-                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.0</code></pre>
+                    <header><span>Direct Pi package only</span><button class="clip-btn" data-clip="pi install git:github.com/Vt-mmm/piagent@v1.0.1">Lấy lệnh</button></header>
+                    <pre><code>pi install git:github.com/Vt-mmm/piagent@v1.0.1</code></pre>
                   </div>
                 </div>
               </article>
@@ -993,9 +993,9 @@ piagent-install --stable</code></pre>
                   <h3>Update hoặc rollback đúng cả ba thành phần</h3>
                   <p>Full update/rollback phải dùng exact Pi host của release target, đổi npm-global helper, rồi apply stable Pi package từ chính helper đó. Lệnh <span class="inline-code">--version ... --resolve-tag</span> chỉ đổi Pi package và giữ host/helper hiện tại.</p>
                   <div class="command-card">
-                    <header><span>Full platform target</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+                    <header><span>Full platform target</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
                     <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable</code></pre>
                   </div>
@@ -1474,9 +1474,9 @@ npm run typecheck</code></pre>
                 <pre><code>piagent-setup --mcp-preset core --subagents-preset safe</code></pre>
               </article>
               <article class="command-card">
-                <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
+                <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
                 <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+npm install -g --ignore-scripts @piagent/platform@X.Y.Z
 piagent-install --stable --dry-run
 piagent-install --stable</code></pre>
               </article>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -11,7 +11,7 @@
   "homepage": "https://piagent.io.vn",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Vt-mmm/piagent.git"
+    "url": "git+https://github.com/Vt-mmm/piagent.git"
   },
   "keywords": [
     "pi-package",

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "private": true,
   "license": "MIT",
@@ -8,7 +8,7 @@
   "homepage": "https://piagent.io.vn",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Vt-mmm/piagent.git",
+    "url": "git+https://github.com/Vt-mmm/piagent.git",
     "directory": "packages/piagent-core"
   },
   "keywords": [

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.0.0 --resolve-tag
+  scripts/install-global.sh --version v1.0.1 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -123,7 +123,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.0.0 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.0.1 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -131,7 +131,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.0 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.1 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/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.0.0 support matrix."
+    note: "This runtime is outside the documented v1.0.1 support matrix."
   };
 }
 

package/scripts/verify-release-identity.mjs

@@ -55,7 +55,11 @@ if (rootPackage.name !== "@piagent/platform") fail("root package must be named @
 if (rootPackage.private) fail("root package must not be private; publishing is intended");
 if (rootPackage.publishConfig?.access !== "public") fail("scoped package must declare publishConfig.access=public");
 if (rootPackage.publishConfig?.provenance !== true) fail("root package must publish with provenance");
-if (rootPackage.repository?.url !== "https://github.com/Vt-mmm/piagent.git") fail("root package repository URL is not canonical");
+// The git+ prefix is npm's own normalization. Publishing without it succeeds
+// but rewrites the field, which leaves the manifest in the repository saying
+// something different from the manifest on the registry.
+if (rootPackage.repository?.url !== "git+https://github.com/Vt-mmm/piagent.git") fail("root package repository URL is not canonical");
+if (corePackage.repository?.url !== rootPackage.repository.url) fail("core package repository URL does not match the root package");
 if (rootPackage.dependencies && Object.keys(rootPackage.dependencies).length > 0) fail("root package has unexpected runtime dependencies");
 if (packageLock.name !== rootPackage.name || packageLock.packages?.[""]?.name !== rootPackage.name) fail("package-lock root identity does not match package.json");
 if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version ?? "")) fail("package.json version is not a supported release version");