@piagent/platform 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.1.0 - 2026-07-26
+
+A document downloaded outside the repository can now be read by the agent, and the two documented install commands stop disagreeing about MCP.
+
+### Added
+
+- Added `piagent_document_read`, which reads a document from a directory outside the project. Downloading a spec to `~/Downloads` and then having no way to hand it to the agent was a dead end with no workaround short of copying the file into the repository. A directory is granted through `additionalReadRoots` in the project profile or the `PIAGENT_ADDITIONAL_READ_ROOTS` environment variable, and the grant widens only where documents may come from. It is read-only. It accepts `.md`, `.markdown`, `.txt`, `.text`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`, `.pdf`, and `.docx`, and refuses every other extension sitting in the same directory. `protectedPaths` still wins over it, matched against both the absolute and the project-relative form of the path so that root-anchored patterns are not silently skipped, and a capability pack that narrows filesystem read scope still narrows it for documents inside the project. Both the containment check and the extension check are made against the canonical path, so a link named `notes.md` cannot hand over the key file it points at.
+- `.docx` is read without a dependency, from a bounds-checked archive reader that names what was wrong with a malformed file rather than reporting every failure as a missing document. Text struck out by an unaccepted tracked change is dropped instead of being spliced onto its replacement, tab-stop declarations no longer emit tab characters, field instruction codes are not read as prose, and a character reference outside the Unicode range is left as written rather than ending the read. `.pdf` goes through `pdftotext`, under a timeout, and a missing binary is reported as missing rather than as an empty document. Byte-order-marked UTF-16 is decoded rather than rejected as binary. Returned text is redacted and enclosed in a data region delimited by a marker the document cannot predict, because a downloaded document is exactly the kind of file that carries both a pasted key and a sentence addressed to an agent.
+- Added `npm run site:check`, which verifies the published documentation site at every address it resolves to instead of once through whichever address a browser happened to pick. It requires each address to return the released version, reports a redirect from an address back to its own host as a loop rather than following it, and reports an address the machine cannot route to as unverified rather than as a pass. Release checklist step 8 was a manual look, and a manual look cannot see a partial outage.
+
+### Changed
+
+- Raised the pinned Pi Coding Agent and Pi AI host from `0.81.1` to `0.82.0`. `typebox` stays exactly `1.1.38` across both, so the pin moves without a compatibility change. `npm run audit:runtime` on the `0.82.0` tree reports one high advisory, the same already-accepted `GHSA-mh99-v99m-4gvg` under review by 2026-08-25, and no critical. Verified against a real `0.82.0` host: runtime policy smoke and `team-doctor --strict-share` both pass with no warnings.
+- `piagent-install` now installs the MCP baseline by default, the same as `piagent-setup` already did, and both accept `--no-mcp` to skip it. The two documented entry points disagreed: `piagent-setup` defaulted to installing MCP and `piagent-install` defaulted to not installing it, so a newcomer who followed the team onboarding document ended up with no MCP at all — and was then told to run `/mcp`, because the installer printed that next step whether or not it had installed anything. That next step is now printed only when MCP was installed, and `--mcp-preset` combined with `--no-mcp` fails instead of being accepted and quietly dropped.
+- Cut the command count in the three places a new user actually lands. The README went from 28 shell blocks to 4 and now opens with install rather than four variants of a wrapper for software the reader has not installed yet; the Vietnamese quickstart went from 23 to 7 and its install step from 120 lines to 28; the documentation site's onboarding flow went from eight install command cards to one. Pinned rollouts, updates, rollback, the `--dev` channel, and per-tool command lists were not deleted — every one of them already had a dedicated document, and each is now linked from where it used to be inlined.
+
+### Fixed
+
+- Writing MCP server definitions now says what each server still needs before it can connect: Chrome for the Chrome DevTools server, Docker plus `GITHUB_PERSONAL_ACCESS_TOKEN` for the GitHub server. Servers connect lazily, so a successful install proved nothing about whether they would work, and the Docker requirement existed only in a description string visible under `piagent-mcp --list`. The note goes to stderr so the report on stdout stays machine-readable, and `--list` now carries the same requirements as data.
+- An advisory tool-registry verdict is now shown. `toolRegistry` defaults to `advisory` and the evaluation returned a `warn` decision, but the hook acted only on `block`, so the verdict was computed and discarded — advisory mode was indistinguishable from off, and the documentation said the agent received a warning. The notice is emitted once per tool per session, because one on every call would be noise rather than a warning.
+- `piagent-uninstall --with-addons` now reports the MCP baseline file that install actually writes. It named the Pi-global override path while install writes the shared global path, so an operator following the printed advice inspected the wrong file — usually an empty one, which reads as "already clean".
+- Project onboarding now says that the `.mcp.json` files it writes are empty on purpose and that the shared baseline lives in the global config. An empty file in a fresh project reads as a failed install.
+- Documented that `mcpCapabilities` in a project profile, the `github` key in the policy tool registry, and the `github` MCP server are three unrelated things that share a name. No code maps a capability name to an MCP server, so declaring `github` in a profile does not enable the GitHub server and never did.
+- `piagent-init` running from an installed package now writes `npm:@piagent/platform@<version>` into project settings, matching what `piagent-setup` already did. It is the second way a project gets its settings written, and it still wrote the directory the platform happened to be installed in — a value that means nothing on a teammate's machine, in a file meant to be committed.
+- Documentation-coverage checks in the local gate now name the term that went missing and the files searched. They were bare `grep >/dev/null` calls under `set -e`, so dropping a term from a document failed the gate with exit 1 and no output at all. The gate's `npm test` and `npm run typecheck` steps had the same defect from the other direction — their output went to `/dev/null` on every run, so a failing test ended the gate with no indication of which test failed. Both now stay quiet on success and print what they captured on failure.
+- Documented that `piagent-setup` installs the Herdr Pi integration when `herdr` is on `PATH`, and that installing Herdr afterwards needs `piagent-setup --global-only` to pick it up. The behaviour has always been the default and the skip is only a warning on stderr, so the ordering was discoverable only by reading the installer. Herdr is also now named as the way to run several Pi panes at once in the README, the quickstart, and the documentation site, none of which mentioned it, and every one of those places now carries the install command itself rather than a link to go find it. The `brew` form is listed beside the `curl` form that herdr.dev leads with, because piping a fetched script to a shell is worth an alternative in a project that pins everything else it installs.
+- Folded a stale `Unreleased` section into v1.0.0, where its contents actually shipped. It had been left behind by the namespace rename and still described tools as `company_orchestration_policy`, `company_profile_tech_options`, `company_profile_tech_apply`, `company_profile_tech_context_record`, and `/company-orchestration`, none of which exist.
+
 ## v1.0.2 - 2026-07-25
 
 Install and uninstall become two commands each. The five-command sequence was never the shortest path; it was the only one that produced a project configuration a teammate could use.
@@ -43,6 +71,8 @@ Breaking release. The `company` namespace is replaced by `piagent` with no alias
 - Added a golden enforcement suite covering protected paths, protected paths reached through the shell, destructive shell decisions, verification evidence, context budget ceilings, and secret redaction, with a valid and an invalid fixture for every shipped schema.
 - Added contributor documentation: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, pull-request and issue templates.
 - Added a tag-driven publish workflow with npm provenance and pinned action revisions.
+- Added a solo-first orchestration policy covering bounded subagent usage, review lenses, Field Guide status, and model-role guidance, surfaced by `piagent_orchestration_policy` and `/piagent-orchestration` so status reads without a model follow-up. Task contracts gained `workPlan`, `reviewLenses`, and `orchestration` snapshots to record it.
+- Added select-style profile tech setup through `/profile setup` and `/profile tech setup`, including fullstack frontend, backend, and database selections. `piagent_profile_tech_options`, `piagent_profile_tech_apply`, and `piagent_profile_tech_context_record` produce Context7-ready stack manifests and per-tech snapshots.
 
 ### Changed
 
@@ -52,6 +82,9 @@ Breaking release. The `company` namespace is replaced by `piagent` with no alias
 - The package is now published rather than private, scoped as `@piagent/platform` with public access and provenance.
 - Split shell and external-action classification, shared types, and filesystem helpers out of the guard into their own modules. Behaviour is unchanged.
 - Onboarding now names instruction files written for other agents, states plainly that their rules are not in effect, and offers the import; anything inside them is treated as data.
+- `/task`, `/plan`, `/review`, the subagent prompts, and the team docs now prefer one parent agent plus bounded scout, planner, and reviewer usage instead of broad swarm-style delegation.
+- Onboarding and docs treat profile family and project tech stack as explicit operator selections rather than long model explanations, and `/profile` status and list output stay compact around the single namespace and the next exact command.
+- Runtime support is stated across macOS Apple Silicon, macOS Intel, Linux x64 and ARM64, native Windows, and WSL2, and the installer and doctor report the runtime surface they are actually on.
 
 ### Fixed
 
@@ -60,34 +93,14 @@ Breaking release. The `company` namespace is replaced by `piagent` with no alias
 - Excluded maintainer working notes from the published tarball. The `files` allowlist takes precedence over `.npmignore`, so the exclusions live in `files`.
 - Fixed the package manifest declaring its extension entry points as a directory glob. Pi calls the default export of every path the field matches, so once the guard's helpers moved into modules beside it, the glob offered Pi two modules that export helpers and no extension factory. The manifest now names the guard, and the package still carried the old `@pi-agent/core` name the namespace rename was meant to retire.
 - Fixed the verify workflow, which had been unparseable since the runtime-platform step was added and so had not run at all. A single-line `run:` value containing `": "` ends the YAML scalar early; GitHub reports that as an instant failure with no job, so the gate was absent while still appearing present. The local gate now refuses that shape.
+- Fixed orchestration config normalization so a malformed numeric setting falls back to a safe value instead of producing invalid policy state.
+- Fixed tag CI verification, which checked tag object type and peeled commit identity without first fetching the annotated release tag ref.
+- Profile doctor and team doctor now warn on entries that appear only in `shellProtectedPaths`. Those paths block shell access alone; write protection requires `protectedPaths` or `readOnlyPaths`, and the warning names the move.
 
 ### Security
 
 - The runtime host audit now names the one advisory it accepts instead of running at a blanket severity threshold. `GHSA-mh99-v99m-4gvg` (`brace-expansion`, denial of service) is accepted with its reasoning recorded in `scripts/check-runtime-advisories.mjs`: the Pi host publishes an `npm-shrinkwrap.json` that pins the affected version, a published shrinkwrap takes precedence over consumer overrides, and every released host carries a high `brace-expansion` advisory, so no host version and no change in this repository can resolve it. Every other high or critical advisory still fails the audit, the entry expires on a review date, and it fails once the advisory stops being reported so it cannot outlive the problem.
 
-## Unreleased
-
-### Added
-
-- Added solo-first orchestration policy for bounded subagent usage, review lenses, Field Guide status, and model-role guidance.
-- Added `company_orchestration_policy` and `/company-orchestration` for compact local orchestration status without a model follow-up.
-- Added task-contract fields for `workPlan`, `reviewLenses`, and `orchestration` snapshots.
-- Added select-style profile tech setup via `/profile setup` and `/profile tech setup`, including fullstack FE/BE/database selections.
-- Added `company_profile_tech_options`, `company_profile_tech_apply`, and `company_profile_tech_context_record` for Context7-ready tech stack manifests and concise per-tech snapshots.
-
-### Changed
-
-- Updated `/task`, `/plan`, `/review`, subagent prompts, and team docs to prefer one parent agent plus bounded scout/planner/reviewer usage instead of broad swarm-style delegation.
-- Updated onboarding/docs to treat profile family and project tech stack as explicit operator selections instead of long model explanations.
-- Tightened `/profile` status/list output around the single namespace and next exact command so the default path stays compact.
-- Clarified runtime support across macOS Apple Silicon, macOS Intel, Linux x64/ARM64, native Windows, and WSL2, and made installer/doctor output report the current runtime surface.
-
-### Fixed
-
-- Hardened orchestration config normalization so malformed numeric settings fall back safely instead of producing invalid policy state.
-- Fixed tag CI verification by fetching the annotated release tag ref before checking tag object type and peeled commit identity.
-- Added profile-doctor and team-doctor warnings for legacy `shellProtectedPaths`-only entries, clarifying that those paths block shell access only and must move to `protectedPaths` or `readOnlyPaths` for write protection.
-
 ## v0.4.8 - 2026-07-22
 
 ### Added

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.0` or a reviewed commit.
 
 Ready for: