@piagent/platform 1.0.2 → 1.1.1

package/README.md

@@ -4,35 +4,66 @@ Reusable Pi package for project onboarding, profile-based coding workflows, guar
 
 Public docs: [piagent.io.vn](https://piagent.io.vn)
 
-The goal is a simple daily flow:
+## Install
+
+Node.js `>=22.19.0`. Two commands, run from the project you want to set up:
 
 ```bash
-cd /path/to/project
-pi
+npm install -g @piagent/platform
+piagent-setup
 ```
 
-From there, Pi can onboard the project, select an operating profile, use the right tools, record task evidence, and hand off verified implementation work.
+`piagent-setup` installs the exact Pi Coding Agent host this release pins, installs the Pi package, initializes the current directory, and runs the doctor. It also installs the MCP baseline, the subagents, and — when `herdr` is already on `PATH` — the Herdr Pi integration; pass `--no-mcp`, `--no-subagents`, `--no-herdr`, or `--global-only` to skip those.
 
-For a trusted project where you want Pi to load project-local `.pi` resources without another trust prompt on that run:
+If you want [Herdr](https://herdr.dev/docs/install/), install it *before* `piagent-setup`:
 
 ```bash
-cd /path/to/project
-piagent-auto
+brew install herdr                            # macOS
+curl -fsSL https://herdr.dev/install.sh | sh  # macOS or Linux
 ```
 
-Read-only scout mode:
+The integration step is skipped with a warning when `herdr` is not on `PATH`, so installing Herdr afterwards means running `piagent-setup --global-only` again. The `curl` form runs a script fetched at install time; `brew` and the [GitHub releases](https://github.com/ogulcancelik/herdr/releases) are the reviewable alternatives. Stable Herdr covers macOS and Linux — Windows builds are preview only, which is outside this platform's rollout matrix either way.
+
+Because it runs from an installed package, the source it writes into `.pi/settings.json` is `npm:@piagent/platform@<version>` — which means the same thing on a teammate's machine, so the file can be committed.
+
+| Runtime surface | Team rollout status |
+|---|---|
+| macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. |
+| Linux x64 + Bash | Verified in CI for this release. |
+| macOS Intel (`darwin/x64`) + Bash | Supported target, but run `piagent-doctor` and project smoke tests before wide rollout. |
+| Linux ARM64 + Bash | Supported target, but run `piagent-doctor` and project smoke tests before wide rollout. |
+| Native Windows | Not a team-rollout target yet; terminal helpers and shell policy rely on Bash/POSIX semantics. |
+| WSL2 | Experimental and not release-gated yet. |
+
+Pinned step-by-step rollouts, updates, rollback, and the fast-moving `--dev` channel are in [Release and install policy](docs/release-install-policy.md).
+
+## Daily use
 
 ```bash
-piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
+cd /path/to/project
+pi
 ```
 
-Trusted full-access style run:
+That is the daily flow. Pi onboards the project, selects an operating profile, uses the right tools, records task evidence, and hands off verified implementation work.
+
+Running several agents side by side — one implementing, one reviewing read-only, one verifying — start `herdr` from the project instead of `pi` and open a Pi pane per role. Herdr orchestrates terminals and sessions; it is not a security boundary, so every gate still lives in the Pi extension and OAuth is still a `/login` inside Pi. See [Herdr workflow](docs/herdr-workflow.md).
+
+First run in a new project, type `/onboard-project`. It inspects the repository with bounded context, recommends a profile, explains the tradeoffs, asks before applying, then writes `.pi/piagent-profile.json`, its lock, `.pi/tech-stack.json`, `.pi/tech-context/*`, `.pi/project-context.md`, and `.pi/memory/*`.
+
+`/piagent-commands` lists everything else. For trusted local runs, `piagent-auto` wraps `pi --approve` and sets a permission profile for that run — it does not bypass protected-path checks, destructive shell checks, task gates, or verification evidence. See the [command reference](docs/command-reference-vietnamese.md).
+
+## Uninstall
+
+`piagent-uninstall` reports what it would remove and exits. It only acts with `--apply`, because it edits Pi settings that other tools also write to.
 
 ```bash
-piagent-auto --full-access -p "Run the trusted local benchmark suite."
+piagent-uninstall
+piagent-uninstall --apply
 ```
 
-`piagent-auto` is a convenience wrapper for Pi project trust (`pi --approve`). It does not bypass protected-path checks, destructive shell checks, task gates, or verification evidence.
+That removes the Pi package this platform registered. Add-ons, the Pi host, a project's state, and the npm-global helper are each opt-in and separate — `piagent-uninstall --help` lists them.
+
+Removal targets what is registered in Pi's settings rather than what the current version installs, so a package registered by an older release still comes out. Credentials, trust decisions, sessions, todos, and project memory are never removed, at any flag combination. Files written from a template and then edited — `AGENTS.md`, `.pi/settings.json`, `.pi/project-context.md` and the like — are listed for review rather than deleted.
 
 ## What it provides
 
@@ -96,172 +127,23 @@ Inside Pi:
 
 This shows the active mode, max subagents, review lenses, Field Guide path, and writer policy without triggering a model follow-up.
 
-## Install
-
-Supported for this release:
-
-| Runtime surface | Team rollout status |
-|---|---|
-| macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. |
-| Linux x64 + Bash | Verified in CI for this release. |
-| macOS Intel (`darwin/x64`) + Bash | Supported target, but run `piagent-doctor` and project smoke tests before wide rollout. |
-| Linux ARM64 + Bash | Supported target, but run `piagent-doctor` and project smoke tests before wide rollout. |
-| Native Windows | Not a team-rollout target yet; terminal helpers and shell policy rely on Bash/POSIX semantics. |
-| WSL2 | Experimental and not release-gated yet. |
-
-Node.js `>=22.19.0` is required. Two commands:
+## Profiles
 
-```bash
-npm install -g @piagent/platform
-piagent-setup
-```
-
-`piagent-setup` installs the exact Pi Coding Agent host this release pins, installs the Pi package, initializes the current directory, and runs the doctor. Run it from the project you want to set up. It also installs the MCP baseline and subagents; pass `--no-mcp` and `--no-subagents` to skip them, or `--global-only` to install nothing into a project.
-
-Because it is running from an installed package, the source it writes into `.pi/settings.json` is `npm:@piagent/platform@<version>`, which means the same thing on a teammate's machine.
-
-To install each component explicitly instead — for a pinned team rollout where every step is reviewed:
-
-```bash
-node --version  # >= 22.19.0
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@1.0.2
-piagent-install --stable --dry-run
-piagent-install --stable
-```
-
-`piagent-install --stable` resolves the helper's release tag to a commit SHA and installs the matching Pi package. In its output, `currentRelease` is the version of the terminal helper currently executing. The project release matrix above defines which OS/CPU surfaces this platform has verified.
-
-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.2
-```
-
-From a checked-out platform repo, the same helper is available as a script:
-
-```bash
-bash scripts/install-global.sh --stable --dry-run
-bash scripts/install-global.sh --stable
-```
-
-For a full update, update the exact Pi host first, then the npm-global helper, then apply its matching stable Pi package:
-
-```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
-npm install -g --ignore-scripts @piagent/platform@X.Y.Z
-piagent-install --stable --dry-run
-piagent-install --stable
-```
-
-For rollback, read the target release's compatibility section and install its exact Pi host before changing the helper to `vPREVIOUS`; older hosts may reintroduce known dependency findings. If you intentionally want to change only the Pi package while keeping the terminal helper at its current version:
-
-```bash
-piagent-install --version vX.Y.Z --resolve-tag --dry-run
-piagent-install --version vX.Y.Z --resolve-tag
-```
-
-Use latest only for a personal machine or sandbox where fast updates are acceptable:
-
-```bash
-bash scripts/install-global.sh --dev --dry-run
-bash scripts/install-global.sh --dev
-```
-
-Optional Herdr integration:
-
-```bash
-herdr integration install pi
-```
-
-## Uninstall
-
-`piagent-uninstall` reports what it would remove and exits. It only acts with `--apply`, because it edits Pi settings that other tools also write to.
-
-```bash
-piagent-uninstall
-piagent-uninstall --apply
-```
-
-That removes the Pi package this platform registered. Everything beyond it is opt-in:
-
-```bash
-piagent-uninstall --apply --with-addons              # pi-mcp-adapter, pi-subagents, pi-web-access
-piagent-uninstall --apply --with-host                # the Pi Coding Agent host
-piagent-uninstall --apply --project /path/to/project # a project's profile, lock, and runtime state
-npm uninstall -g @piagent/platform                   # the npm-global helper, removed separately
-```
-
-Removal targets what is registered in Pi's settings rather than what the current version installs, so a package registered by an older release still comes out.
-
-Credentials, trust decisions, sessions, todos, and project memory are never removed, at any flag combination. Files written from a template and then edited — `AGENTS.md`, `.pi/settings.json`, `.pi/project-context.md` and the like — are listed for review rather than deleted. A project's `.pi/settings.json` keeps every setting except the package entry pointing at this platform.
-
-## Daily use
-
-```bash
-cd /path/to/project
-pi
-```
-
-First run inside a project:
+Switching profile is one command inside Pi:
 
 ```text
-/login
-/model
-/scoped-models      # optional: customize Ctrl+P model cycle
-/piagent-commands
-/mcp                # inspect MCP servers
-/subagents-doctor   # health check
-/onboard-project
-/memory-policy
+/profile             # status
+/profile fullstack   # apply
+/profile setup       # select profile, then select the tech for each role
 ```
 
-`/onboard-project` will inspect the repository with bounded context, recommend a profile, explain tradeoffs, ask before applying, then write:
-
-- `.pi/piagent-profile.json`
-- `.pi/piagent-profile.lock.json`
-- `.pi/tech-stack.json`
-- `.pi/tech-context/*`
-- `.pi/project-context.md`
-- `.pi/memory/*`
-
-Switch profiles later:
-
-```text
-/profile                 # short status, no model follow-up
-/profile list            # compact profile list
-/profile fullstack       # apply immediately
-/profile be-readonly-fe  # apply immediately
-/profile web-frontend    # apply immediately
-/profile backend-api     # apply immediately
-/profile auto            # apply detected recommendation
-/profile fe              # alias for web-frontend
-/profile be-fe           # alias for be-readonly-fe
-/profile setup           # select profile, then select role tech
-/profile setup fullstack # select FE, BE, and database tech
-/profile tech            # short tech stack status
-/profile tech setup fullstack
-/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma
-```
-
-The setup flow prefers native select UI. If the Pi host does not expose a select control yet, it falls back to a compact options card and an exact `/profile tech apply ...` command instead of asking the model to explain every option.
+`/profile list` shows every profile and its aliases. The setup flow prefers a native select UI; where the Pi host has no select control, it falls back to a compact options card and an exact `/profile tech apply ...` line rather than asking the model to explain every option.
 
 ## Capability packs
 
-Capability packs group governed prompts, skills, subagents, policies, adapters, recipes, and eval scenarios behind a declarative manifest. Project profiles select exact pack versions and explicitly grant owner, lifecycle, filesystem, network, and external-action boundaries.
+Capability packs group governed prompts, skills, subagents, policies, adapters, recipes, and eval scenarios behind a declarative manifest. Project profiles select exact pack versions and explicitly grant owner, lifecycle, filesystem, network, and external-action boundaries. The generated lock is deterministic and records profile, pack, artifact, and permission digests.
 
-```bash
-piagent-capabilities catalog --check
-piagent-capabilities doctor \
-  --profile .pi/piagent-profile.json \
-  --lock .pi/piagent-profile.lock.json
-piagent-capabilities resolve \
-  --profile .pi/piagent-profile.json \
-  --output .pi/piagent-profile.lock.json \
-  --package-source ../
-```
-
-The generated lock is deterministic and records profile, pack, artifact, and permission digests. See [Capability packs](docs/capability-packs.md).
+Commands and lock format: [Capability packs](docs/capability-packs.md).
 
 ## Built-in profiles
 
@@ -281,125 +163,34 @@ The generated lock is deterministic and records profile, pack, artifact, and per
 
 ## Main workflows
 
-### General implementation
-
-```text
-/task Implement <bounded task>. Follow profile, required context, protected paths, verify commands, and trace.
-```
-
-Use `/task` when the requirement is clear enough to implement.
-
-### Guarded Git workflows
-
-Pi Agent intentionally keeps Git as a capability instead of adding a `/git-*` namespace. Use short workflow commands or natural language:
-
-```text
-/commit docs: update onboarding notes
-/pr Add guarded git workflow
-```
-
-`/commit` starts a governed local-commit workflow: inspect status/diff, stage only the intended files, run relevant verification, then commit locally. It does not push.
-
-`/pr` starts a governed pull-request workflow: inspect branch/status/commits, handle uncommitted changes explicitly, then ask for confirmation before any `git push` or GitHub PR create/update action. Draft PRs are the default unless the user asks for ready-for-review.
-
-Broad staging commands such as `git add .`, `git add -A`, `git add --all`, `git add -- .`, and `git add :/` require confirmation so unrelated or private files are not swept into a commit silently.
-
-For read-only investigation:
-
-```text
-/scout Scout <module/spec/contract/risk>. Do not edit source.
-```
-
-Use `/scout` for payment/auth/data/BE-contract mapping before deciding whether to implement.
-
-When the current session is already heavy, use the fresh workflow commands. They open a new governed Pi session and replay the compact workflow prompt automatically:
+Everything below is typed inside a Pi session. `/piagent-commands` lists the full set; [command reference](docs/command-reference-vietnamese.md) explains each one.
 
-```text
-/fresh-task <request>
-/fresh-scout <read-only request>
-/fresh-be-to-fe <backend-readonly/frontend request>
-```
-
-The input guard also collapses pasted mandatory-flow boilerplate automatically. Users should not paste the full piagent checklist into every task.
-
-### Screenshots and local images
-
-If a chat box paste or screen capture produces a local image path instead of a native Pi image attachment, paste the path directly in the task:
-
-```text
-/scout Check this UI state from screenshot /var/folders/.../screenshot.png
-```
-
-The input guard converts supported local image paths (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`) into Pi image attachments and rewrites the prompt to:
-
-```text
-/scout Check this UI state from screenshot [image1]
-```
-
-Limits: up to 4 chat images, 8 MB each. For oversized images, use Pi's `read` tool on the file so Pi can resize it.
-
-### Project improvement
-
-```text
-/platform-improve Improve <platform/setup/workflow behavior>. Update docs and verification.
-```
-
-Use `/platform-improve` for package-level work such as setup, MCP, model scope, memory, runtime policy, prompts, skills, or subagent workflows.
-
-### Backend spec to frontend
-
-```text
-/profile be-readonly-fe
-/be-to-fe Implement frontend support for <backend endpoint/spec>. Backend is read-only.
-```
+| Command | Use when |
+|---|---|
+| `/task <request>` | The requirement is clear enough to implement. |
+| `/scout <request>` | Read-only investigation — payment, auth, data, or backend-contract mapping — before deciding whether to implement. |
+| `/discuss <rough request>` | The requirement is not clear yet. |
+| `/plan <goal>` | You want a plan before any edit. |
+| `/review current diff` | Reviewing work already done. |
+| `/commit <message>` | Governed local commit: inspect status and diff, stage only the intended files, run verification, commit. Never pushes. |
+| `/pr <title>` | Governed pull request: confirms before any `git push` or GitHub write. Draft by default. |
+| `/be-to-fe <request>` | Backend or spec is read-only and the implementation target is frontend. Pair with `/profile be-readonly-fe`. |
+| `/platform-improve <request>` | Package-level work: setup, MCP, model scope, memory, runtime policy, prompts, skills, subagents. |
+| `/fresh-task`, `/fresh-scout`, `/fresh-be-to-fe` | The current session is already heavy. Opens a new governed session and replays the compact workflow prompt. |
 
-Use `/be-to-fe` when the backend/spec must be inspected read-only and the implementation target is frontend.
+Git stays a capability rather than a `/git-*` namespace, so natural language works too. Broad staging — `git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/` — requires confirmation, so unrelated or private files are not swept into a commit silently.
 
-### Planning and clarification
+Paste a local screenshot path straight into a task and the guard attaches it as `[image1]` before the model sees the prompt: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, up to 4 images at 8 MB each. The guard also collapses pasted mandatory-flow boilerplate, so there is no need to paste a checklist into every task.
 
-```text
-/discuss <rough request>
-/plan <goal>
-/review current diff
-```
+A spec that lives outside the project — the one just downloaded to `~/Downloads` — is read with `piagent_document_read` once its directory is listed in the profile's `additionalReadRoots`. The grant is read-only, covers `.md`, `.txt`, `.csv`, `.json`, `.yaml`, `.pdf`, and `.docx` only, and does not open anything `protectedPaths` covers. See [command reference](docs/command-reference-vietnamese.md).
 
 ## Model selection
 
-Model selection is handled by Pi’s native UI.
-
-```text
-/model          # selector
-Ctrl+L          # selector hotkey
-/scoped-models  # edit model cycle scope
-Ctrl+P          # cycle scoped models
-Shift+Tab       # cycle thinking level when supported by the selected model
-```
-
-Global setup can seed `enabledModels`. To inspect or re-apply:
-
-```bash
-piagent-models
-piagent-model-scope --preset full
-```
+Handled by Pi's native UI: `/model` or `Ctrl+L` to pick, `Ctrl+P` to cycle the scoped set, `Shift+Tab` to cycle thinking level where the model supports it. Global setup seeds `enabledModels`; see [Model options](docs/model-options.md) to inspect or re-apply it.
 
 ## MCP setup
 
-Global setup installs `pi-mcp-adapter` and seeds the `core` MCP preset unless disabled.
-
-```bash
-piagent-mcp --preset core --scope global --replace
-piagent-mcp --preset popular --scope global --replace
-piagent-mcp --preset design --scope project --project /path/to/project
-piagent-mcp --list
-```
-
-If the repo is cloned from Git and npm bins are not linked yet:
-
-```bash
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
-```
-
-Preset summary:
+`piagent-setup` and `piagent-install` both install `pi-mcp-adapter` and seed the `core` preset. Pass `--no-mcp` to skip it.
 
 | Preset | Includes |
 |---|---|
@@ -407,59 +198,15 @@ Preset summary:
 | `popular` | core + Playwright + Figma remote |
 | `all` | popular + Figma desktop/local |
 
-Keep secrets in environment variables, never in committed config:
+Seeding writes server definitions; it does not start or authenticate anything. Servers connect lazily, so each one needs its own prerequisite before its first call: Chrome DevTools needs a local Chrome, and GitHub needs Docker running plus `GITHUB_PERSONAL_ACCESS_TOKEN` exported. `piagent-mcp --list` prints what each server requires. Project-scope `.mcp.json` files ship empty on purpose — the shared baseline is the global config, not the project one.
 
-```bash
-export CONTEXT7_API_KEY=ctx7sk_...
-export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
-```
+Keep provider keys in environment variables, never in committed config. Switching presets and per-project scoping: [MCP and tools](docs/mcp-and-tools.md).
 
 ## Subagents
 
-Global setup installs `pi-subagents` and applies the `safe` preset unless disabled.
-
-```bash
-piagent-subagents --preset safe
-```
+`piagent-setup` installs `pi-subagents` with the `safe` preset unless disabled. Daily task prompts stay solo-first: they delegate bounded scout, planning, and review work only when it is independent enough to be worth the cost, and the final handoff states whether subagents were used and why.
 
-Fallback when cloned from Git without npm bins:
-
-```bash
-bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
-```
-
-Common Pi commands:
-
-```text
-/subagents-doctor
-/subagents-models
-/subagents-fleet
-/subagent-cost
-/run piagent-scout "Map the auth flow. Read-only."
-/run piagent-planner "Plan implementation from context.md."
-/run piagent-worker "Implement the approved plan."
-/run piagent-reviewer "Review current diff."
-```
-
-Daily task prompts are solo-first: they can delegate bounded scout/planning/review work when useful, and the final handoff should state whether subagents were used and why.
-
-Optional web/docs research support:
-
-```bash
-pi install npm:pi-web-access@0.13.0
-```
-
-## Optional preseed setup
-
-Most projects do not need shell init. Use this only when you want to pre-create `.pi` files in a repo or bootstrap team templates:
-
-```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.2 \
-  --mcp-preset core \
-  --subagents-preset safe
-```
+`/subagents-doctor` runs a health check; `/run piagent-scout "…"` and its planner, worker, and reviewer counterparts dispatch work. See [Subagents and multi-agent](docs/subagents-and-multiagent.md).
 
 ## Repository layout
 
@@ -479,49 +226,13 @@ piagent/
 
 ## Verification
 
-```bash
-npm ci --ignore-scripts --legacy-peer-deps
-npm run typecheck
-npm test
-npm run benchmark:redaction
-bash scripts/verify-local.sh
-bash scripts/team-doctor.sh . --strict-share
-pi list --approve
-```
-
-Quality benchmark:
-
-```bash
-bash scripts/quality-benchmark.sh /path/to/project --init
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens 12345 \
-  --verify "npm test"
-```
-
-Sensitive-data redaction benchmark:
+One command runs the full local gate — typecheck, tests, capability catalog, doctor, and the scaffold check:
 
 ```bash
-npm run benchmark:redaction
-```
-
-Usage / token follow-up:
-
-```text
-/task-preflight
-/task-preflight compact
-/piagent-usage
-/session
+npm run verify
 ```
 
-From another terminal:
-
-```bash
-piagent-usage /path/to/project
-bash scripts/pi-session-stats.sh /path/to/project
-```
+Individual checks and the contributor flow are in [CONTRIBUTING.md](CONTRIBUTING.md). Token and session follow-up is `/piagent-usage` inside Pi; see [Usage observability](docs/usage-observability.md). Comparing agent surfaces and models on the same scenarios: [Quality benchmark guide](docs/quality-benchmark.md).
 
 ## Public safety
 
@@ -559,6 +270,7 @@ This repository intentionally excludes:
 - [Subagent orchestration capabilities](docs/subagent-orchestration-capabilities.md)
 - [Context-window policy](docs/context-window-policy.md)
 - [Memory policy](docs/memory-policy.md)
+- [Task lifecycle tiếng Việt](docs/task-lifecycle-vietnamese.md)
 - [Task implementation contract](docs/task-implementation-contract.md)
 - [Runtime quality baseline](docs/runtime-quality-baseline.md)
 - [Usage observability](docs/usage-observability.md)
@@ -571,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.0.2` 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.1` or a reviewed commit.
 
 Ready for:
 

package/docs/command-reference-vietnamese.md

@@ -177,6 +177,45 @@ Tech stack option theo profile:
 
 Sau khi chọn tech, platform tạo `.pi/tech-stack.json` và các file `.pi/tech-context/<tech>.json`. `/onboard-project` sẽ đưa các pointer này vào `.pi/context-index.json`. File context chỉ nên chứa tóm tắt ngắn/citation từ Context7, không lưu nguyên văn docs dài, token, session, hoặc secret.
 
+## Đọc tài liệu ngoài project
+
+Tài liệu tải về `~/Downloads` rồi kéo vào CLI thường không đọc được, vì mặc định agent chỉ làm việc trong project. Tool `piagent_document_read` mở đúng một khe: đọc **tài liệu**, **chỉ đọc**, trong các folder đã cấp trước.
+
+| Thành phần | Giá trị |
+|---|---|
+| Tool | `piagent_document_read` |
+| Input | `path` — absolute, `~/...`, hoặc relative theo project |
+| Định dạng | `.md`, `.markdown`, `.txt`, `.text`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`, `.pdf`, `.docx` |
+| Giới hạn | 12 MB/file; 400.000 ký tự sau khi trích, dài hơn thì cắt và báo `truncated` |
+| Cấp quyền | `additionalReadRoots` trong `.pi/piagent-profile.json`, hoặc biến môi trường `PIAGENT_ADDITIONAL_READ_ROOTS` |
+
+Cấp folder cố định trong profile:
+
+```json
+{
+  "additionalReadRoots": ["~/Downloads", "~/Documents/specs"]
+}
+```
+
+Cấp tạm cho một session, ngăn cách bằng `:` giống `PATH`:
+
+```bash
+PIAGENT_ADDITIONAL_READ_ROOTS="$HOME/Downloads:$HOME/Documents/specs" pi
+```
+
+Sau đó nói thẳng path là được: `Đọc ~/Downloads/spec-v2.docx rồi tóm tắt yêu cầu`.
+
+Bốn ràng buộc không đổi khi cấp thêm root:
+
+- **Chỉ đọc.** Root được cấp không mở quyền ghi, xoá, hay chạy lệnh trong đó.
+- **Chỉ tài liệu.** File nằm trong root được cấp nhưng sai đuôi — `.pem`, `.sh`, `.env` — vẫn bị từ chối.
+- **`protectedPaths` luôn thắng.** Root được cấp không mở được path mà project đang bảo vệ.
+- **Nội dung là dữ liệu, không phải lệnh.** Text trả về đã qua redaction và có header nói rõ đây là dữ liệu người dùng; câu lệnh viết trong tài liệu không được thi hành.
+
+Cả hai kiểm tra — nằm trong root và đúng đuôi — đều chạy trên path đã canonical hoá. Nên symlink trong root mà trỏ ra ngoài bị chặn, và symlink tên `notes.md` trỏ vào `id_rsa` cũng bị chặn.
+
+`.docx` đọc trực tiếp, không cần cài gì; text bị xoá bởi tracked change chưa accept sẽ không lẫn vào nội dung. `.pdf` cần `pdftotext` (macOS `brew install poppler`, Debian/Ubuntu `apt install poppler-utils`); thiếu binary thì tool báo thiếu chứ không trả tài liệu rỗng.
+
 ## Command native của Pi
 
 Các command này thuộc Pi core hoặc package Pi chính. Tên/availability có thể phụ thuộc version Pi.
@@ -379,11 +418,11 @@ 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 @piagent/platform@1.0.2` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.0.2` | Cài pinned release khi cần reproducible team setup. |
+| `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.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.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 @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, npm-global helper và Pi package. v1.0.2 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. 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á 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. |