@piagent/platform 1.0.0

package/docs/quickstart-vietnamese.md

@@ -0,0 +1,350 @@
+# Quickstart tiếng Việt
+
+> Nếu cần hướng dẫn đầy đủ từ setup, command, token/session, MCP đến subagents, xem `docs/operator-manual-vietnamese.md`.
+
+## Mục tiêu
+
+Sau setup, flow hằng ngày là:
+
+```bash
+cd <project>
+pi
+```
+
+Phần còn lại — OAuth, package, context, harness, MCP, tool-call guard — nằm trong repo/package `piagent-platform`.
+
+## Bước 1 — install runtime và package
+
+Support matrix của release hiện tại:
+
+| Runtime | Trạng thái |
+|---|---|
+| macOS Apple Silicon + Bash | Đã verify cho release này. |
+| Linux x64 + Bash | Đã verify trong CI. |
+| macOS Intel + Bash | Supported target; chạy `piagent-doctor` và smoke test project trước khi rollout rộng. |
+| Linux ARM64 + Bash | Supported target; chạy `piagent-doctor` và smoke test project trước khi rollout rộng. |
+| Native Windows | Chưa phải target rollout team; helper/shell policy cần Bash/POSIX semantics. |
+| WSL2 | Experimental, chưa release-gate. |
+
+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
+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.
+
+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
+```
+
+Nếu đang ở source checkout của platform, có thể preview và áp stable bằng helper:
+
+```bash
+bash scripts/install-global.sh --stable --dry-run
+bash scripts/install-global.sh --stable
+```
+
+Helper stable sẽ resolve tag release hiện tại thành commit SHA trước khi install, nên user vẫn dùng lệnh ngắn nhưng team nhận source bất biến hơn.
+
+Khi update toàn bộ platform, cập nhật exact Pi host trước rồi dùng helper target để cài Pi package tương ứ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
+piagent-install --stable --dry-run
+piagent-install --stable
+```
+
+Rollback toàn bộ dùng cùng flow với `vPREVIOUS`, nhưng phải lấy exact host version từ release policy của target và đánh giá lại dependency risk trước khi hạ host. Nếu chủ ý chỉ đổi Pi package và giữ host/helper hiện tại:
+
+```bash
+piagent-install --version vX.Y.Z --resolve-tag --dry-run
+piagent-install --version vX.Y.Z --resolve-tag
+```
+
+Checklist release canonical nằm tại [release-install-policy.md](release-install-policy.md).
+
+Máy cá nhân hoặc sandbox có thể dùng latest nếu chấp nhận cập nhật nhanh:
+
+```bash
+bash scripts/install-global.sh --dev --dry-run
+bash scripts/install-global.sh --dev
+```
+
+Sau bước này, project mới không cần chạy bash init profile. Chỉ cần:
+
+```bash
+cd /path/to/project
+pi
+```
+
+Với project đã tin cậy, có thể dùng wrapper để Pi tự approve project-local resources cho lần chạy đó:
+
+```bash
+piagent-auto
+```
+
+Read-only auto-run:
+
+```bash
+piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
+```
+
+Trusted full-access style run cho repo đã kiểm soát:
+
+```bash
+piagent-auto --full-access -p "Run the trusted local benchmark suite."
+```
+
+Wrapper này không bypass piagent guard; nó wrap `pi --approve` và set permission profile cho lần chạy. Dù dùng `--full-access`, protected paths, redaction, destructive shell checks, task gate, và verify evidence vẫn chạy.
+
+Nếu đã ở trong Pi session, dùng slash command cho nhanh:
+
+```text
+/permission-status
+/full-access Implement/refactor task trong repo trusted này.
+```
+
+`/full-access <task>` chỉ bật full-access cho session hiện tại, không tự ghi `.pi/piagent-profile.json`.
+
+Nếu chat box/ảnh chụp trả về local path thay vì attachment ảnh, dán path đó trực tiếp vào prompt:
+
+```text
+/scout Check UI issue from screenshot /var/folders/.../screenshot.png
+```
+
+Platform sẽ tự attach ảnh và rewrite prompt thành `[image1]` trước khi model xử lý. Hỗ trợ `.png/.jpg/.jpeg/.gif/.webp/.bmp`, tối đa 4 ảnh, 8 MB mỗi ảnh.
+
+## Bước 2 — login OAuth OpenAI Codex/ChatGPT hoặc Claude/Anthropic
+
+```bash
+pi
+/login
+```
+
+Chọn provider OpenAI/Codex/ChatGPT hoặc Anthropic/Claude trong danh sách Pi. Token được lưu local trong Pi agent dir, không nằm trong repo.
+
+## Bước 3 — chọn model và chạy project onboarding
+
+Sau khi login và chọn model intended cho project understanding:
+
+```text
+/model          # hoặc Ctrl+L để chọn model bằng selector của Pi
+/scoped-models  # optional, chỉnh danh sách Ctrl+P cycle
+/piagent-commands
+/mcp            # kiểm tra MCP adapter/server
+/subagents-doctor  # health check subagent setup
+/onboard-project
+/context-index
+/memory-policy
+```
+
+Global setup đã config sẵn `enabledModels` cho các provider model families. Anh đổi model bằng selector/hotkey:
+
+```text
+Ctrl+L       # model selector
+Ctrl+P       # đổi model trong scope
+Shift+Tab    # đổi thinking
+```
+
+Nếu muốn xem/re-apply model scope từ terminal: `piagent-models` và `piagent-model-scope --preset full`.
+
+Nếu muốn xem/re-apply MCP baseline từ terminal:
+
+```bash
+piagent-mcp --preset core --scope global --replace
+piagent-mcp --preset popular --scope global --replace
+piagent-mcp --list
+```
+
+Nếu clone repo GitHub và chưa link npm bin, dùng fallback:
+
+```bash
+bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+```
+
+Nếu muốn xem/re-apply subagents baseline từ terminal:
+
+```bash
+piagent-subagents --preset safe
+# fallback:
+bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
+```
+
+Nếu muốn dùng builtin `researcher` cho web/docs research trong Pi:
+
+```bash
+pi install npm:pi-web-access@0.13.0
+# hoặc setup từ đầu:
+bash /path/to/piagent/scripts/setup.sh . --with-web-access
+```
+
+Lệnh này yêu cầu model đọc qua project theo phạm vi có kiểm soát, rồi ghi:
+
+```text
+.pi/piagent-profile.json
+.pi/piagent-profile.lock.json
+.pi/tech-stack.json
+.pi/tech-context/*.json
+.pi/project-context.md
+.pi/context-index.json
+.pi/memory/memory_summary.md
+.pi/memory/MEMORY.md
+```
+
+Nếu chưa có profile/tech stack, dùng select-style flow để tránh agent trả lời dài:
+
+```text
+/profile setup
+/profile tech setup fullstack
+```
+
+`web-frontend` chọn FE + database optional; `backend-api` chọn BE + database optional; `fullstack` chọn frontend, backend và database. Nếu Pi host chưa có native select, command sẽ trả card ngắn và lệnh deterministic `/profile tech apply ...`.
+
+`.pi/project-context.md` là snapshot context cho task sau. `.pi/context-index.json` là bản đồ node/edge/citation compact để tìm đúng điểm vào repo; vẫn phải đọc source hiện tại trước khi sửa. Không đọc/ghi raw file index trong task thường ngày; dùng `/context-index`, `/onboard-project` hoặc `piagent_context_index_record` để runtime sanitize dữ liệu advisory. Nếu snapshot còn `Generated: not yet` hoặc `/context-index` báo pending/stale, agent phải dừng trước task lớn và yêu cầu chạy `/onboard-project`.
+
+`/memory-policy` kiểm tra chính sách memory của project. Mặc định memory là explicit-only: chỉ ghi khi user yêu cầu rõ “remember this”, không tự học transcript nền.
+
+## Bước 4 — init thêm project khác
+
+```bash
+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 \
+  --mcp-preset core \
+  --subagents-preset safe
+```
+
+Đổi profile sau này trong Pi:
+
+```text
+/profile list
+/profile setup
+/profile tech setup
+/profile be-readonly-fe
+```
+
+Profile built-in: `generic`, `web-frontend`, `backend-api`, `be-readonly-fe`, `fullstack`, `node-typescript`, `python`, `data`, `devops`, `mobile`, `docs`.
+
+## Bước 5 — setup split/preseed nếu cần
+
+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 \
+  --mcp-preset core \
+  --subagents-preset safe
+```
+
+## Bước 6 — chạy hằng ngày
+
+```bash
+herdr
+cd <project>
+pi
+```
+
+Prompt mẫu khi requirement chưa rõ:
+
+```text
+/discuss Cải tiến workflow onboarding cho team mới. Chưa implement, chỉ hỏi lại phần còn thiếu và đề xuất plan.
+```
+
+Prompt mẫu khi đã rõ task:
+
+```text
+/task Implement this request. Use piagent_context, piagent_task_start, piagent_context_budget, piagent_exec_policy_check when shell is needed, piagent_verify_record, piagent_trace_record, and piagent_task_gate_check before done.
+```
+
+Prompt mẫu khi chỉ cần scout/read-only:
+
+```text
+/scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
+```
+
+Nếu session đang nặng hoặc gặp context overflow:
+
+```text
+/fresh-scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
+/fresh-task Implement <bounded task>.
+/fresh-be-to-fe Implement FE support from <BE contract>. Backend read-only.
+```
+
+Không paste full mandatory flow hằng ngày. Từ `v0.3.21`, input guard tự collapse mandatory-flow boilerplate và fresh workflow tự mở session mới khi cần.
+
+Từ `v0.3.21`, `/task` có auto-delegation policy. Với task đủ lớn, parent agent phải tự cân nhắc dùng `piagent-scout`, `piagent-planner`, hoặc `piagent-reviewer`; anh không cần tự gọi `/run` nếu không muốn ép orchestration.
+
+Các workflow package đáng dùng khi muốn ép rõ shape:
+
+```text
+/parallel-review current diff
+/review-loop current diff max 3 rounds
+/parallel-research <question cần external evidence + local code context>
+/parallel-context-build <task lớn cần context handoff>
+```
+
+Prompt mẫu cho 2 recipe hay gặp:
+
+```text
+/piagent-commands subagents
+/platform-improve Improve model selection, MCP setup, and onboarding docs for a public team package.
+/be-to-fe Implement FE from BE spec <endpoint/spec>. Backend read-only.
+/context-index search auth
+/memory-policy Show project memory policy and safe remember workflow.
+/run piagent-scout "Map target area read-only before planning."
+/run piagent-reviewer "Review current diff before final handoff."
+```
+
+Cache external source repo để đọc targeted trong Pi:
+
+```text
+Use piagent_source_checkout for github.com/org/repo, inspect only relevant files, then summarize applicable patterns.
+```
+
+Runtime gate tools có sẵn:
+
+```text
+piagent_exec_policy_check      # check shell command
+piagent_context_budget         # check context size/hard cap
+piagent_tool_policy_check      # check tool capability
+piagent_task_gate_check        # check before final DONE
+```
+
+Fallback bằng shell nếu cần:
+
+```bash
+PIAGENT_PLATFORM_HOME=/path/to/piagent
+bash "$PIAGENT_PLATFORM_HOME/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh" \
+  github.com/org/repo \
+  --path-only
+```
+
+## Việc user vẫn phải làm thủ công
+
+- Login OAuth lần đầu trong browser.
+- Chọn provider/model intended cho project.
+- Chạy `/onboard-project` lần đầu để tạo `.pi/project-context.md` và `.pi/context-index.json`.
+- Chạy `/memory-policy` nếu muốn kiểm tra hoặc dùng project memory.
+- Approve project trust nếu Pi hỏi. Sau khi hiểu rõ repo, có thể dùng `piagent-auto` hoặc Pi native `--approve` cho từng lần chạy.
+- Approve khi extension guard hỏi destructive/high-risk action.
+
+Các việc này là credential/trust boundary, không nên automation mù.
+
+## Tài liệu chính
+
+- Command reference: `docs/command-reference-vietnamese.md`
+- Pi packages: https://pi.dev/docs/latest/packages
+- Pi extensions: https://pi.dev/docs/latest/extensions
+- Pi providers/OAuth: https://pi.dev/docs/latest/providers
+- Pi settings/trust: https://pi.dev/docs/latest/settings
+- Pi MCP adapter: https://pi.dev/packages/pi-mcp-adapter

package/docs/release-install-policy.md

@@ -0,0 +1,223 @@
+# Release and install policy
+
+## Purpose
+
+Pi Agent Platform uses explicit release sources for team rollout. Personal machines may follow a moving source when fast iteration matters, but team environments and committed project settings use exact tags or reviewed commits so every developer receives the same platform package.
+
+This file is the canonical install, update, rollback, and release checklist. Other docs link here instead of maintaining a second release procedure.
+
+## Supported runtime matrix
+
+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 |
+|---|---|---|
+| 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. |
+| macOS Intel (`darwin/x64`) + Bash | Supported target; not currently a dedicated release-gate runner. | Run `piagent-doctor` plus the target project's smoke/verify suite before broad rollout. |
+| Linux ARM64 + Bash | Supported target; not currently a dedicated release-gate runner. | Run `piagent-doctor` plus the target project's smoke/verify suite before broad rollout. |
+| Native Windows x64/ARM64 | Not supported for team rollout in this release. | Node is available on Windows, but platform helper scripts and shell parsing assume Bash/POSIX semantics. Use a verified macOS/Linux surface for release-critical work. |
+| WSL2 | Experimental and not release-gated. | Treat as local/personal until a WSL lane and smoke suite are added. |
+
+## Runtime and two installation planes
+
+| 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`. |
+| 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.
+
+## Release channels
+
+| 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. |
+| `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. |
+
+`--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.
+
+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
+
+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
+piagent-install --stable --dry-run
+piagent-install --stable
+```
+
+The stable preview and apply output includes:
+
+```text
+currentRelease: v1.0.0 (helper package version)
+tag: v1.0.0
+resolvedCommit: <40-char-sha>
+source: git:github.com/Vt-mmm/piagent@<40-char-sha>
+```
+
+From a checked-out platform repository, the same Pi-package install is available as:
+
+```bash
+bash scripts/install-global.sh --stable --dry-run
+bash scripts/install-global.sh --stable
+```
+
+## First install — Pi package only
+
+Use this only when terminal commands are not needed:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent@v1.0.0
+```
+
+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:
+
+```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
+piagent-install --stable --dry-run
+piagent-install --stable
+piagent-doctor /path/to/project --strict-share
+```
+
+Review the target `CHANGELOG.md` before applying the update. Confirm that `currentRelease`, `tag`, and `resolvedCommit` all describe the intended release.
+
+## Pi-package-only update
+
+This flow changes the Pi package but intentionally leaves the npm-global helper unchanged:
+
+```bash
+piagent-install --version vX.Y.Z --resolve-tag --dry-run
+piagent-install --version vX.Y.Z --resolve-tag
+piagent-doctor /path/to/project --strict-share
+```
+
+Alternatively, install a reviewed Pi source directly:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent@vX.Y.Z
+```
+
+`pi update --extensions` refreshes configured package refs. It does not move a pinned project from one tag or commit to a different target; install the new reviewed ref explicitly.
+
+## Full platform rollback
+
+Rollback the host, helper, and Pi package together. Determine the exact host version from the target release's compatibility section before running this sequence; do not assume the current host is supported by an older helper.
+
+```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
+piagent-install --stable --dry-run
+piagent-install --stable
+piagent-doctor /path/to/project --strict-share
+```
+
+Older host versions may reintroduce dependency findings fixed by the current release; treat that as an explicit rollback risk. Restore project state only if the older package cannot read a newer profile, lock, or runtime-state format. Preserve the current state separately before restoring a project snapshot.
+
+## Pi-package-only rollback
+
+Use this when terminal helpers must remain at their current version:
+
+```bash
+piagent-install --version vPREVIOUS --resolve-tag --dry-run
+piagent-install --version vPREVIOUS --resolve-tag
+piagent-doctor /path/to/project --strict-share
+```
+
+## Canonical release checklist
+
+Production docs must never advertise a tag that cannot yet be installed.
+
+### Required GitHub repository controls
+
+Before broad team access, a repository administrator must enable these external controls; source files cannot turn them on:
+
+1. Create an active branch ruleset for `main` that requires a pull request, blocks force-push and deletion, and requires the checks shown by the workflows, including `verify (ubuntu-latest)`, `verify (macos-latest)`, `analyze (actions)`, and `analyze (javascript-typescript)`. Add one narrowly scoped release-maintainer bypass actor for the exact non-force fast-forward promotion described below; do not give this bypass to the normal team role.
+2. Create an active tag ruleset targeting `v*`. Restrict creation to the maintainer/release role and block tag update and deletion. This is mandatory because the first npm-global helper install uses a release tag before that helper can resolve its Pi-package source to a commit SHA.
+3. Enable Dependency graph, Dependabot alerts, and Dependabot security updates. Keep `.github/dependabot.yml` enabled for scheduled npm and GitHub Actions update pull requests.
+4. Enable GitHub private vulnerability reporting so the form linked by `SECURITY.md` works before public rollout.
+5. Keep secret scanning and push protection enabled. Review CodeQL results after the workflow's first successful run.
+
+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.
+
+1. Update package versions, `CHANGELOG.md`, install examples, and docs metadata on a release-candidate branch.
+2. Verify the exact release-candidate source:
+
+   ```bash
+   npm run verify
+   npm test
+   npm run typecheck
+   npm run smoke
+   npm run benchmark:redaction
+   npm audit --audit-level=high
+   npm run audit:runtime
+   npm run release:identity
+   npm pack --dry-run --json
+   bash scripts/setup.sh --global-only --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z --dry-run
+   ```
+
+3. Push the release-candidate branch, open a pull request to `main`, and wait for both Ubuntu/macOS verify jobs and both CodeQL matrix jobs to pass. Record the exact PR-head commit SHA that passed; do not merge it into the Vercel production branch yet, and do not tag a later unverified edit.
+4. Create an annotated, reviewed tag on that exact verified commit and push the tag:
+
+   ```bash
+   RC_COMMIT=<verified-40-char-pr-head-sha>
+   git tag -a vX.Y.Z "$RC_COMMIT" -m "Pi Agent Platform vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+   Use a signed tag when the maintainer signing setup is available. Tag CI requires an annotated tag, verifies that it equals `v<package-version>`, checks that its peeled commit equals the checked-out release SHA, confirms root/core/capability-lock/docs versions agree, requires the stable installer to resolve back to that same SHA, and runs high-severity dependency gates for both the helper tree and exact Pi host + pinned add-ons. Wait for the tag-triggered Ubuntu and macOS CI jobs to pass before continuing.
+
+5. Verify the remote tag and confirm stable resolution points to the tagged commit:
+
+   ```bash
+   git ls-remote --tags origin refs/tags/vX.Y.Z 'refs/tags/vX.Y.Z^{}'
+   RELEASE_COMMIT="$(git rev-parse vX.Y.Z^{})"
+   PIAGENT_EXPECTED_RELEASE_COMMIT="$RELEASE_COMMIT" bash scripts/install-global.sh --stable --dry-run --no-model-scope
+   ```
+
+6. Create a draft GitHub release from the matching `CHANGELOG.md` section. Keep it unpublished until production docs are verified:
+
+   ```bash
+   gh release create vX.Y.Z --draft --verify-tag --title "vX.Y.Z" --notes-file /tmp/pi-agent-vX.Y.Z-release-notes.md
+   ```
+
+7. Only after tag CI and stable SHA verification pass, the designated release maintainer uses the ruleset bypass for a non-force fast-forward of the exact tagged commit to `main`. Do not merge, squash, rebase, or introduce a different commit during promotion:
+
+   ```bash
+   git fetch --tags origin main:refs/remotes/origin/main
+   RELEASE_COMMIT="$(git rev-parse vX.Y.Z^{})"
+   test "$(git merge-base origin/main "$RELEASE_COMMIT")" = "$(git rev-parse origin/main)"
+   git push origin "$RELEASE_COMMIT:refs/heads/main"
+   ```
+
+   The open release pull request should then resolve against the same commit history. This bypass exists only to reconcile reviewed PR checks with tag-first Vercel promotion; it must never be used for an unreviewed commit or a force-push. If Vercel auto-deploys `main`, this exact fast-forward is the production promotion. For an explicit CLI deploy instead, check out the exact tag, run `vercel link --cwd docs-site --project pi-agent`, require `npm run vercel:preflight` to pass, then deploy with `vercel --cwd docs-site --prod`.
+8. Verify the live docs version, links, canonical domain, and install commands.
+9. Publish the already-reviewed draft only after production verification passes:
+
+   ```bash
+   gh release edit vX.Y.Z --draft=false
+   ```
+
+10. Announce the release, then roll out with the full platform update flow above and run doctor/smoke checks on representative team projects.
+
+## Security notes
+
+- Do not use a moving source in committed project settings.
+- Do not publish local trust files, OAuth tokens, `auth.json`, sessions, caches, or `.env` files.
+- Review the resolved commit SHA before rollout; tag resolution improves reproducibility but is not signed package provenance by itself.
+- `npm audit --audit-level=high` covers this repository's helper dependency tree. `npm run audit:runtime` separately builds and audits the exact optional Pi host and pinned add-on dependency tree so `--legacy-peer-deps` cannot hide deployed runtime findings.
+- Run doctor after install, update, or rollback so package source, project profile, protected paths, and share policy are checked together.

package/docs/runtime-harness-standard.md

@@ -0,0 +1,118 @@
+# Runtime harness standard
+
+## Mục tiêu
+
+Runtime harness là “máy vận hành task” dùng chung cho nhiều project:
+
+```text
+User request
+  -> project profile
+  -> intake/risk lane
+  -> required context manifest
+  -> plan / task contract
+  -> guarded tool calls
+  -> implementation
+  -> observed verify evidence
+  -> trace / handoff
+```
+
+Project cụ thể chỉ cần adapter/profile riêng. Core package giữ lifecycle, policy, verification, và documentation flow.
+
+## Reusable modules
+
+| Module | Pi Agent Platform target | Lý do |
+|---|---|---|
+| Risk lane | `riskLane` + profile `hardGates` | Chặn auth, release, provider config, destructive action, database migration. |
+| Intake | `piagent_task_start` | Mỗi task có scope, output, acceptance criteria trước khi edit. |
+| Context rules | `/onboard-project`, `.pi/project-context.md`, `requiredContext`, context manifest | Giảm token và tránh đọc toàn repo. |
+| Test matrix | `verifyCommands` + observed verify evidence | DONE phải có exact verify command thực chạy qua Pi bash hoặc `N/A` rõ lý do. |
+| Trace | `piagent_trace_record`, `.pi/piagent-state/traces.jsonl`, session entry | Có audit trail cho task. |
+| Protected paths | `protectedPaths` trong profile + extension guard | Mỗi project có vùng cấm riêng. |
+| Tool registry | `mcpCapabilities` + `.mcp.json` | Không tự đoán tool/MCP. |
+| Domain contract | Project docs/profile | Chỉ project cần UX/form/data strict mới bật. |
+
+## Không đưa vào core
+
+| Không đưa vào core | Lý do |
+|---|---|
+| Project-specific DB/state | Không portable giữa project. |
+| Project-specific story IDs | Mỗi team cần namespace riêng. |
+| Project-specific FE/BE rules | Làm core bị khóa vào một repo. |
+| Toàn bộ skill library của một máy local | Gây collision và context bloat. |
+| Prompt dài cho mọi trường hợp | Nên dùng lifecycle + profile + context manifest. |
+
+## Workflow prompts
+
+- `/platform-improve`: update package/platform behavior.
+- `/be-to-fe`: scout backend/spec read-only, create contract snapshot, implement frontend only.
+- `/task`: governed implementation lifecycle.
+- `/plan`: create implementation plan.
+- `/discuss`: clarify before work.
+- `/review`: review diff/source with evidence.
+
+## Task lifecycle chuẩn
+
+```text
+1. Intake
+   - risk lane
+   - expected output
+   - acceptance criteria
+   - out of scope
+   - protected paths
+
+2. Context
+   - load piagent_context
+   - read `.pi/project-context.md`
+   - read requiredContext
+   - check large files with piagent_context_budget
+   - record context manifest
+
+3. Plan
+   - exact touchpoints
+   - verify command
+   - rollback/handoff if high-risk
+
+4. Implement
+   - check risky shell with piagent_exec_policy_check
+   - check non-piagent tools with piagent_tool_policy_check
+   - edit only in scope
+   - avoid protected paths
+
+5. Verify
+   - run exact mapped verify command
+   - store evidence
+   - if verify unavailable: not DONE
+
+6. Trace
+   - changed files
+   - commands
+   - result
+   - friction
+   - next step
+   - piagent_task_gate_check before DONE
+```
+
+## Maturity phases
+
+| Phase | Output | Đủ để implement task? |
+|---|---|---|
+| P0 | package core + profile + docs + protected path guard | Chỉ đủ pilot/read-only. |
+| P1 | schema + task contract + doctor + verify-local + lean prompts | Dùng được cho task nhỏ có review. |
+| P2 | extension tools for task/context/verify/trace + session entries | Dùng được cho source task có guard rõ. |
+| P3 | exec policy + context budget + tool registry + task gate + benchmark recorder | Dùng được cho guarded project workflows. |
+| P4 | stronger worktree/sandbox/team governance | Cần project-specific dry run trước khi làm default. |
+
+## Chuẩn DONE
+
+Một Pi task chỉ DONE khi có đủ:
+
+- profile loaded;
+- lane classified;
+- protected paths known;
+- context manifest exists;
+- plan exists for source write;
+- changed files listed;
+- exact verify command ran and passed, hoặc explicitly `N/A` với reason;
+- trace/handoff recorded;
+- no secrets touched;
+- no protected path writes.