@piagent/platform 1.1.9 → 1.2.1

package/docs/model-options.md

@@ -1,6 +1,8 @@
 # Model selector and scope
 
-Pi Agent Platform không khóa vào một provider. OpenAI Codex và Claude/Anthropic đều là first-class option.
+Pi Agent Platform không khóa vào một provider. Hai họ model dưới đây đều là first-class option: **model OpenAI Codex** (provider id `openai-codex`) và **model Claude của Anthropic** (provider id `anthropic`).
+
+Lưu ý cách đọc: trong toàn bộ tài liệu này, "Codex" và "Claude" là **tên họ model** đứng sau các provider id ở trên. Chúng không phải tên CLI, và cũng không phải một agent nào khác — mọi thứ ở đây đều chạy trong Pi.
 
 Quan trọng: flow chính là user chọn model bằng native Pi selector, không phải hỏi agent recommend.
 
@@ -48,7 +50,7 @@ piagent-models --provider openai-codex
 piagent-models --provider anthropic
 ```
 
-Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, Claude có thể chưa hiện dù model catalog local có metadata.
+Lưu ý: `--list-models` chỉ hiện model mà Pi xem là available với credential/provider hiện tại. Nếu chưa login Anthropic, các model Claude có thể chưa hiện dù model catalog local có metadata.
 
 ## Thinking levels
 
@@ -70,7 +72,7 @@ pi --thinking medium
 
 Đừng giới hạn vào vài ví dụ. Sau `pi update --models`, kiểm tra catalog local bằng `piagent-models`. Ở release hiện tại, các family/presets chính cần nhớ:
 
-### OpenAI Codex
+### Họ model OpenAI Codex
 
 | Model | Role gợi ý | Khi dùng |
 |---|---|---|
@@ -82,14 +84,14 @@ pi --thinking medium
 | `openai-codex/gpt-5.6-sol` | strategic/deep | architecture, large refactor, planning lớn |
 | `openai-codex/gpt-5.6-terra` | huge-context scout | đọc nhiều docs/source, tổng hợp repo lớn |
 
-### Claude / Anthropic
+### Họ model Claude (Anthropic)
 
 | Model | Role gợi ý | Khi dùng |
 |---|---|---|
 | `anthropic/claude-haiku-4-5` | fast/cheap | hỏi nhanh, docs/scout nhẹ |
 | `anthropic/claude-sonnet-4-5` | balanced | task source bình thường |
 | `anthropic/claude-sonnet-4-6` | balanced/deep | source task lớn hơn, max-capable |
-| `anthropic/claude-sonnet-5` | balanced/hard default | Claude default mạnh cho implement |
+| `anthropic/claude-sonnet-5` | balanced/hard default | model default mạnh cho implement |
 | `anthropic/claude-opus-4-5` | deep | review/refactor lớn |
 | `anthropic/claude-opus-4-6` | deep/max | architecture/reasoning nặng |
 | `anthropic/claude-opus-4-7` | deep/xhigh/max | high-risk/debug/architecture |
@@ -102,7 +104,7 @@ Pi catalog có thể có thêm dated variants như `*-2025xxxx`. Dùng alias lat
 
 Preset dưới đây là cách mình seed `enabledModels`, không phải giới hạn hard. User vẫn có thể mở `/model` để chọn bất kỳ model available nào trong provider catalog.
 
-| Preset | OpenAI Codex example | Claude/Anthropic example | Khi dùng |
+| Preset | Model OpenAI Codex | Model Claude (Anthropic) | Khi dùng |
 |---|---|---|---|
 | Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | đọc nhanh, hỏi đáp, grep/scout nhẹ |
 | Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | task source bình thường |
@@ -160,6 +162,6 @@ bash scripts/quality-benchmark.sh /path/to/project --record \
 
 So sánh tối thiểu:
 
-- Pi + Codex fast/balanced/deep;
-- Pi + Claude fast/balanced/deep;
+- Pi + model Codex ở fast/balanced/deep;
+- Pi + model Claude ở fast/balanced/deep;
 - any other approved setup nếu team muốn so sánh bằng số liệu.

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.1.9`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.2.1`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -154,7 +154,7 @@ Trong Pi:
 /login
 ```
 
-Chọn provider/account như OpenAI/Codex hoặc Anthropic/Claude. Credential nằm trong Pi user dir, không nằm trong repo và không được commit.
+Chọn provider/account cho họ model muốn dùng: OpenAI (model Codex) hoặc Anthropic (model Claude). Credential nằm trong Pi user dir, không nằm trong repo và không được commit.
 
 Browser login của OpenAI có hai chỗ trông như treo. Cả hai là lỗi Pi host, không phải platform, và còn nguyên ở `0.82.0` lẫn `0.82.1`.
 
@@ -281,7 +281,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.1.9 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.1 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -298,7 +298,7 @@ Khi command không có trên PATH, dùng script trực tiếp:
 
 ```bash
 bash /path/to/piagent/scripts/init-project.sh /path/to/project --profile auto
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
 ```
 
@@ -514,6 +514,16 @@ bash /path/to/piagent/scripts/pi-session-stats.sh \
   /Users/<user>/.pi/agent/sessions/<project-key>/<session>.jsonl
 ```
 
+Để xem tổng usage lịch sử trên máy, kể cả session đã end:
+
+```bash
+piagent-usage --history /path/to/project --days 7
+piagent-usage --history --all-projects --days 7 --csv
+piagent-usage --history --all-projects --since 2026-07-20 --until 2026-07-26 --json
+```
+
+History mode đọc trực tiếp `~/.pi/agent/sessions/**/*.jsonl`. Mặc định có tính cả subagent session files vì đó là usage thật của máy; thêm `--no-subagents` nếu chỉ muốn parent/main sessions.
+
 ### Cách đọc số
 
 | Field | Ý nghĩa |
@@ -654,7 +664,7 @@ piagent-mcp --list
 Fallback:
 
 ```bash
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 ```
 
 ### Cấu hình project
@@ -666,7 +676,7 @@ piagent-mcp --preset design --scope project --project /path/to/project
 Fallback:
 
 ```bash
-bash /path/to/piagent/scripts/configure-mcp.sh \
+node /path/to/piagent/scripts/mcp-manage.mjs \
   --preset design \
   --scope project \
   --project /path/to/project
@@ -854,8 +864,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.1.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.9` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.1` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -880,7 +890,9 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 | `pi --fork <id-or-file>` | Fork session cũ sang session mới. |
 | `pi --name "<name>"` | Đặt tên session. |
 | `pi --tools read,grep,find,ls -p "Review src"` | Read-only one-shot. |
-| `piagent-usage /path/to/project` | Exact token/cost stats. |
+| `piagent-usage /path/to/project` | Exact token/cost stats của session mới nhất. |
+| `piagent-usage --history /path/to/project --days 7` | Tổng usage lịch sử của project. |
+| `piagent-usage --history --all-projects --days 7 --csv` | CSV report cuối tuần toàn máy. |
 | `piagent-mcp --preset core --scope global --replace` | Setup or update the governed MCP baseline. |
 | `piagent-subagents --preset safe` | Setup subagents baseline. |
 | `bash scripts/verify-local.sh` | Verify platform repo. |
@@ -952,7 +964,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 command -v piagent-install
 ```
 
@@ -960,7 +972,7 @@ Nếu đang làm việc từ source checkout, có thể dùng script trực ti
 
 ```bash
 bash /path/to/piagent/scripts/pi-session-stats.sh /path/to/project
-bash /path/to/piagent/scripts/configure-mcp.sh --preset core --scope global --replace
+node /path/to/piagent/scripts/mcp-manage.mjs --preset core --scope global --replace
 bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
 ```
 

package/docs/publishing-for-teams.md

@@ -52,6 +52,8 @@ pi install /path/to/piagent
 - `1.1.7`: update global không còn chặn project đang chạy — lock chỉ block khi grant thật sự đổi, và profile dạng `extends` nhận policy từ platform đang cài thay vì giữ bản copy lúc onboard.
 - `1.1.8`: Pi báo ngay ở đầu session khi có release mới, kèm lệnh chạy update.
 - `1.1.9`: notice update hiện đúng trên bản cài bằng `pi install git:` — bản cài nhận diện theo vị trí thư mục, không theo `.git`.
+- `1.2.0`: `piagent-mcp` quản lý server đầy đủ, server do repo mang theo phải được duyệt mới dùng được, và `/piagent-mcp` là command trong session chứ không phải nhờ model chạy bash.
+- `1.2.1`: approval gate thật sự phủ direct tool và server đến qua `imports` — hai đường vòng mà bản `1.2.0` để hở; kèm một loạt fix về containment khi vendor, độ sâu shell guard, và credential trong URL.
 
 ## Không publish
 

package/docs/quickstart-vietnamese.md

@@ -50,14 +50,14 @@ Xong. Từ đây project nào cũng chỉ cần `cd` vào rồi gõ `pi`.
 
 Rollout team pin từng bước, update, rollback, và channel `--dev` cho máy cá nhân: [release-install-policy.md](release-install-policy.md).
 
-## Bước 2 — login OAuth OpenAI Codex/ChatGPT hoặc Claude/Anthropic
+## Bước 2 — login OAuth provider model (OpenAI/ChatGPT hoặc 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.
+Chọn provider cho họ model muốn dùng trong danh sách Pi: OpenAI/ChatGPT cho model Codex, hoặc Anthropic cho model Claude. 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
 

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.1.9 | Rollout guidance |
+| Surface | Status for v1.2.1 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.9` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.2.1` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.1.9 (helper package version)
-tag: v1.1.9
+currentRelease: v1.2.1 (helper package version)
+tag: v1.2.1
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.1.9
+pi install git:github.com/Vt-mmm/piagent@v1.2.1
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -21,7 +21,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.9, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.2.1, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes
@@ -40,12 +40,13 @@ The final category is outside the containment capability of the Piagent guard. I
 | Vector | Current control | Residual risk |
 |---|---|---|
 | Direct or nested path-like tool input | Bounded recursive input inspection, protected-path precedence, repository boundary checks, filesystem capability scopes, and read-only profile paths | A new carrier or field name must be classified before it can be treated as controlled. Unknown/ambiguous tools fail closed where policy requires confirmation. |
+| Shell glob reaching a protected file | Glob candidates are read from the same expanded, resolved word list as every other check and matched against examples of each protected pattern, so a pattern assembled by an expansion (`{cat,.env*}`, `cat $({echo,.env*})`, `{bash,} -c 'cat .env*'`, `echo .env* | xargs cat`) is seen. This is the only check that can answer for a pattern at all, since `.env*` matches no protected literal. Whether a word is matched against filenames is decided per character, so a quoted metacharacter names a file instead (`{".env*",x}`). A redirection is read by the rule the shell uses — it opens its target only where that target expands to exactly one word, and is refused as an ambiguous redirect otherwise (`> "{.env,}"{,}`, `> {.env,other}`), while a word that can still disappear, an unset variable or a pattern under `nullglob`, leaves the count unknowable and keeps every candidate | Matching is against generated examples of each protected pattern, not against the filesystem, so a protected pattern whose examples do not represent every real name it covers can leave a matching file unnamed. Bounded expansion refuses rather than enumerates when a glob is too broad to expand. |
 | Encoding, case variation, traversal, or symbolic-link alias | Single percent decode, case-insensitive protected matching, canonical resolution for existing paths, traversal/repository escape rejection | Filesystem races and code executing outside observed tool paths require an OS boundary. |
-| Shell glob, brace, redirection, wrapper, assignment, or command composition | Static Bash operand/action analysis with bounded expansion and regression cases; protected input is denied and external mutation is confirmation-gated | Runtime-generated interpreter payloads cannot be fully understood by static parsing. Sensitive output redaction is a backstop, not containment. |
+| Shell glob, brace, redirection, wrapper, assignment, or command composition | Static Bash operand/action analysis with bounded expansion and regression cases; protected input is denied and external mutation is confirmation-gated. A path the analysis cannot resolve — literal text concatenated with a substitution, as in `.en$(echo v)` — is refused rather than matched on its literal half | Runtime-generated interpreter payloads cannot be fully understood by static parsing. Sensitive output redaction is a backstop, not containment. |
 | Secret returned in tool output | Shared contextual redaction across guarded text/results and synthetic recall benchmark | High-entropy, novel secret formats, or transformed output such as base64-encoded content can evade pattern-based redaction. Never intentionally print real secrets. |
 | Malicious project profile or relaxed capability lock | Trust-aware profile loading, deterministic lock digest, base-policy/source integrity, protected self-state, and fail-closed verification | An already trusted malicious repository can execute code through mechanisms outside the guard. |
 | External GitHub/HTTP/MCP/provider mutation | Direct and proxied action classification plus explicit operator confirmation, including guarded shell carriers | Provider semantics and new tool schemas can change; new integrations require policy and regression review. |
-| Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. |
+| Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile. A target written as a command substitution is evaluated only where its body is one plain command with literal operands and a format this renderer reproduces exactly, and confirmed otherwise — a separator, a nested substitution, a redirection, a variable, quoting, an escape, a `printf` option, or a `printf` conversion whose result this does not reproduce (`*`, `%q`, `%b`, the numeric conversions, `%%`) all make the body unreadable here. A constant width or precision and format reuse are reproduced, so a target built from those is refused rather than confirmed, and the rendered output is read as a path candidate as well as the format's literal text and its arguments — a name assembled across a conversion (`.e%.1sv nv` is `.env`) appears in none of the pieces. Brace expansion, ranges included, is performed once per segment before anything reads it, so the rules, the legacy patterns, the nested-interpreter scan, the pipeline producers and the destructive checks all see the word list the shell would build rather than the text as typed; the expansion produces a token stream, so a command and its arguments assembled from one brace word (`{cat,.env}`) are read as both; quoting is tracked per character, so a word holding a quoted group beside an expanding one (`"{.env,}"{,}`) expands exactly as far as the shell expands it — and a target that is nothing but an unresolved parameter expansion is confirmed rather than permitted, since it can hold any value including root. The same holds for reads: a word that is only an unresolved parameter expansion is confirmed wherever the command opens files (`cat ${HOME:+.env}`), including across a pipe into an `xargs` that opens them (`echo $F \| xargs cat`), while a command substitution in that position is left to the nested scan that classifies the command inside it, and two expansions with nothing between them count as a name being assembled just as literal text beside one does. Brace expansion, parameter expansion and command substitution are performed once per segment, in the order a shell performs them, and every reader takes that one word list — so a name assembled by an expansion (`r$(printf %s m) -rf /`, `xa$(printf %s rgs)`, `$(printf %s ba)$(echo -n sh) -c '...'`) is the command it becomes rather than the text it was typed as. A name that still cannot be resolved is treated as an unknown command rather than a known-harmless one: it is enough to bring the destructive checks, the interpreter scan and the file-operand net into play, since `${X:+r}m -rf /` and `${X:+cat} ${X:+.env}` are those commands whenever the variable is set. Differential cases are generated rather than enumerated, over the cross product the defects live in — expansion form, position in the command, and reader — with each spelling placed in the command name, the operand, a flag's argument, a redirection target, a pipeline producer, an `xargs` consumer and an interpreter payload; the corpus fails if any generated spelling produced no word list, so a batch that dies early cannot pass as coverage, and it asserts in both directions so a check that answers for everything fails too | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. A target produced by any other command is knowable only at run time, so it is gated by confirmation rather than refused. |
 | Forged verification result | Observed Bash result ledger, command hash, task-start ordering, exit-code and verify-command matching | Compromise of the trusted Pi/process environment is outside this evidence model. |
 | Mutable or substituted release source | Exact team tags, stable tag-to-commit resolution, release-commit binding in tag CI, annotated-tag requirement, add-on integrity checks, and documented tag ruleset requirement | Bootstrap helper installation still relies on GitHub tag immutability; repository administrators must prevent tag update/deletion. Signed provenance remains future work. |
 | Dependency or package-content compromise | `--ignore-scripts` bootstrap installs, root and exact runtime dependency audits, immutable Action SHAs, package allowlist, artifact tests, CodeQL, Dependabot, secret scanning, and push protection | Audits are point-in-time and lower-severity/upstream findings remain. Review alerts and refresh pins continuously. |

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 piagent-install --stable
 cd /path/to/project
 pi
@@ -42,7 +42,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.9
+npm install -g --ignore-scripts @piagent/platform@1.2.1
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -70,7 +70,7 @@ piagent-update --check
 piagent-update --project /path/to/project
 ```
 
-`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.9`.
+`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.2.1`.
 
 Không cần ai nhớ đi kiểm tra: khi có release mới, Pi tự báo ngay ở dòng notice lúc mở session, kèm luôn lệnh chạy.
 
@@ -129,7 +129,7 @@ Nếu browser login của OpenAI trông như treo, xem [login provider](operator
 
 ## Bước 3 — chọn model và onboard project
 
-Sau login, chọn provider/model intended cho project understanding bằng native Pi selector. OpenAI Codex và Claude/Anthropic đều là supported option.
+Sau login, chọn provider/model intended cho project understanding bằng native Pi selector. Cả hai họ model đều là supported option: model OpenAI Codex và model Anthropic Claude.
 
 ```text
 /model          # hoặc Ctrl+L

package/docs/usage-observability.md

@@ -88,6 +88,35 @@ Ví dụ output:
 }
 ```
 
+## Usage lịch sử / report tuần
+
+`piagent-usage /path/to/project` chỉ trả exact stats của session mới nhất. Để xem tổng usage đã lưu trên máy, kể cả session đã end hoặc subagent runs:
+
+```bash
+piagent-usage --history /path/to/project
+piagent-usage --history /path/to/project --days 7
+piagent-usage --history --all-projects --days 7 --csv
+piagent-usage --history --all-projects --since 2026-07-20 --until 2026-07-26 --json
+```
+
+History mode đọc trực tiếp `~/.pi/agent/sessions/**/*.jsonl`, cộng usage từ từng assistant message:
+
+- `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, `totalTokens`;
+- `cost.total`;
+- số user messages, assistant messages, tool calls, tool results;
+- breakdown theo project và top sessions.
+
+Mặc định history mode **bao gồm subagent session files** vì đó là usage thật của máy. Dùng `--no-subagents` khi chỉ muốn parent/main sessions.
+
+Format hỗ trợ:
+
+| Format | Lệnh |
+|---|---|
+| Human table | `piagent-usage --history <project>` |
+| JSON | `piagent-usage --history <project> --json` |
+| CSV | `piagent-usage --history <project> --csv` |
+| Markdown | `piagent-usage --history <project> --markdown` |
+
 ## Cách đọc số
 
 | Field | Ý nghĩa |

package/docs/vercel-docs-site.md

@@ -19,6 +19,30 @@ Lý do:
 
 Tách repository chỉ nên dùng khi docs cần domain, quyền truy cập, hoặc lịch phát hành riêng.
 
+## Cấu trúc site
+
+Site là nhiều trang tĩnh, mỗi topic một trang, sinh ra từ một shell dùng chung:
+
+```text
+docs-site/
+  content/<slug>.html   # nội dung riêng của từng trang, không có header/sidebar/footer
+  assets/docs.css       # style dùng chung
+  assets/docs.js        # sidebar filter, TOC, active-section, copy button
+  <slug>.html           # output đã generate, được commit
+  vercel.json
+scripts/build-docs-site.mjs
+```
+
+Sidebar chia theo bốn nhóm — Get started, Build, MCP, Operate. Thứ tự nhóm và thứ tự trang nằm trong hằng `NAV` của `scripts/build-docs-site.mjs`; đó cũng là thứ tự của link prev/next ở cuối mỗi trang. Thêm một trang = thêm `docs-site/content/<slug>.html` + một entry trong `NAV`, rồi build lại.
+
+```bash
+npm run site:build
+```
+
+Output HTML được commit, vì Vercel serve file tĩnh và không có build step. `npm run verify` chạy `build-docs-site.mjs --check`, fail khi output đã commit không còn khớp source — cùng cách `catalog/capabilities.json` đang dùng. Không sửa tay `docs-site/<slug>.html`; sửa fragment trong `content/` hoặc sửa shell trong script.
+
+Version badge xuất hiện trên mọi trang, nên `npm run release:identity` kiểm tra tất cả `docs-site/*.html` chứ không riêng `index.html`.
+
 ## Production promotion policy
 
 Production docs không được advertise một release tag chưa tồn tại.
@@ -96,16 +120,22 @@ curl -I https://www.piagent.io.vn/
 curl -sSL https://piagent.io.vn/ | grep 'vX.Y.Z docs'
 ```
 
-Xác nhận thêm favicon/logo, GitHub/Facebook links, install commands, sidebar anchors và mobile layout.
+Xác nhận thêm favicon/logo, GitHub/Facebook links, install commands, sidebar anchors và mobile layout. Vì site giờ là nhiều trang, kiểm tra thêm clean URL và asset dùng chung:
+
+```bash
+curl -o /dev/null -s -w '%{http_code}\n' https://piagent.io.vn/mcp
+curl -o /dev/null -s -w '%{http_code}\n' https://piagent.io.vn/assets/docs.css
+```
 
 ## Local preview
 
 ```bash
-cd docs-site
-python3 -m http.server 4173
+npm run site:preview
 ```
 
-Mở `http://localhost:4173`.
+Mở `http://localhost:4321`. Đổi port bằng `npm run site:preview -- --port 4173`.
+
+Dùng script này thay vì một static server bất kỳ: `vercel.json` bật `cleanUrls`, nên link nội bộ trỏ tới `/quickstart` chứ không phải `/quickstart.html`. `python3 -m http.server` trả 404 cho tất cả các link đó và preview thành vô dụng để kiểm tra navigation. Script bind loopback và resolve extensionless path đúng như production.
 
 ## Security notes
 

package/docs-site/architecture.html

@@ -0,0 +1,152 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Kiến trúc repo · Pi Agent Platform Docs</title>
+    <meta name="description" content="Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được." />
+    <meta name="theme-color" content="#050505" />
+    <link rel="canonical" href="https://piagent.io.vn/architecture" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <meta property="og:title" content="Kiến trúc repo · Pi Agent Platform Docs" />
+    <meta property="og:description" content="Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được." />
+    <meta property="og:url" content="https://piagent.io.vn/architecture" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/docs.css" />
+    <script src="/assets/docs.js" defer></script>
+  </head>
+  <body>
+    <header class="topbar">
+      <a class="brand" href="/" aria-label="Pi Agent Platform">
+        <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
+        <span>Pi Agent Platform</span>
+      </a>
+      <div class="top-actions">
+        <span class="pill"><span class="pill-dot"></span>v1.2.1 docs</span>
+        <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+          GitHub
+        </a>
+        <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
+        <a class="button" href="/commands">Commands</a>
+      </div>
+    </header>
+
+    <div class="layout with-toc">
+      <aside class="sidebar" data-sidebar>
+        <div class="sidebar-search" aria-label="Tìm trong tài liệu">
+          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+            <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+          </svg>
+          <input type="search" placeholder="Tìm trang" data-filter />
+        </div>
+
+        <nav aria-label="Tài liệu">
+          <div class="nav-group">
+            <p class="nav-title">Get started</p>
+            <a class="nav-link" href="/">Overview</a>
+            <a class="nav-link" href="/quickstart">Quickstart</a>
+            <a class="nav-link" href="/scope">Phạm vi platform</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Build</p>
+            <a class="nav-link" href="/profiles">Project profile</a>
+            <a class="nav-link" href="/permissions">Permission modes</a>
+            <a class="nav-link" href="/commands">Command catalog</a>
+            <a class="nav-link" href="/workflows">Workflows</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">MCP</p>
+            <a class="nav-link" href="/mcp">MCP overview</a>
+            <a class="nav-link" href="/mcp-servers">Quản lý server</a>
+            <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
+            <a class="nav-link" href="/mcp-approval">Approval gate</a>
+          </div>
+          <div class="nav-group">
+            <p class="nav-title">Operate</p>
+            <a class="nav-link" href="/security">Security model</a>
+            <a class="nav-link current" href="/architecture" aria-current="page">Architecture</a>
+            <a class="nav-link" href="/runtime">Runtime tools</a>
+            <a class="nav-link" href="/team">Team usage</a>
+          </div>
+        </nav>
+      </aside>
+
+      <main>
+        <div class="content-shell" data-article>
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              <a href="/">Docs</a>
+              <span aria-hidden="true">/</span>
+              <span>Operate</span>
+              <span aria-hidden="true">/</span>
+              <span>Architecture</span>
+            </nav>
+            <div class="page-head">
+              <h1>Kiến trúc repo</h1>
+              <p>Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được.</p>
+            </div>
+<section class="section">
+
+  <div class="grid cols-3">
+    <article class="card">
+      <h3 id="core-package">Core package</h3>
+      <p><span class="inline-code">packages/piagent-core</span> chứa extension guard, prompts, skills và subagent roles.</p>
+    </article>
+    <article class="card">
+      <h3 id="adapters">Adapters</h3>
+      <p><span class="inline-code">adapters/</span> chứa profile dùng lại: frontend, backend, fullstack, data, devops, docs.</p>
+    </article>
+    <article class="card">
+      <h3 id="capability-packs">Capability packs</h3>
+      <p><span class="inline-code">packs/</span> gom policy, lifecycle, recipes và eval scenarios theo manifest có lock.</p>
+    </article>
+    <article class="card">
+      <h3 id="policies">Policies</h3>
+      <p>Base policy định nghĩa protected paths, command rules, permission modes và human-action gates.</p>
+    </article>
+    <article class="card">
+      <h3 id="scripts">Scripts</h3>
+      <p>Setup, doctor, model scope, MCP, subagents, benchmark và trusted-run wrapper đều có CLI riêng.</p>
+    </article>
+    <article class="card">
+      <h3 id="docs">Docs</h3>
+      <p><span class="inline-code">docs/</span> giữ manual dài. <span class="inline-code">docs-site/</span> là trang HTML gọn cho team.</p>
+    </article>
+  </div>
+</section>
+            <nav class="pager" aria-label="Trang kế tiếp">
+              <a class="pager-prev" href="/security">
+                <span class="pager-label">Trước</span>
+                <span class="pager-title">Security model</span>
+              </a>
+              <a class="pager-next" href="/runtime">
+                <span class="pager-label">Tiếp</span>
+                <span class="pager-title">Runtime tools</span>
+              </a>
+            </nav>
+
+            <footer class="footer">
+              <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
+              <div class="footer-links" aria-label="External links">
+                <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
+                <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
+                <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
+              </div>
+            </footer>
+        </div>
+      </main>
+
+      <aside class="toc" aria-label="Mục lục trang">
+        <p class="toc-title">Trên trang này</p>
+        <nav data-toc></nav>
+      </aside>
+    </div>
+  </body>
+</html>