@piagent/platform 1.0.0

package/docs/team-onboarding.md

@@ -0,0 +1,333 @@
+# Team onboarding
+
+> Team mới nên đọc `docs/operator-manual-vietnamese.md` trước, rồi dùng file này như checklist onboarding.
+
+## Mục tiêu
+
+Một thành viên mới không cần biết local path của maintainer. Luồng chuẩn rút gọn:
+
+```bash
+node --version  # >= 22.19.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+piagent-install --stable
+cd /path/to/project
+pi
+/login
+<select provider/model>
+/mcp
+/subagents-doctor
+/onboard-project
+/memory-policy
+```
+
+## Prerequisites
+
+- Node.js >=22.19.0.
+- Pi Coding Agent `0.81.1`.
+- Runtime rollout:
+  - verified: macOS Apple Silicon + Bash, Linux x64 + Bash;
+  - supported target cần smoke trước khi rollout rộng: macOS Intel + Bash, Linux ARM64 + Bash;
+  - chưa dùng làm target rollout team: native Windows; WSL2 chỉ experimental.
+- `pi` có trên `PATH`.
+- `herdr` optional nhưng nên có nếu team chạy nhiều agent pane.
+- Git access tới repo platform nếu dùng `git:` package source.
+- OAuth/API access riêng của từng người. Không share token.
+
+## Bước 1 — install global package một lần
+
+Mặc định team dùng stable helper:
+
+```bash
+node --version  # >= 22.19.0
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0
+piagent-install --stable --dry-run
+piagent-install --stable
+```
+
+`currentRelease` trong output là version của npm-global helper đang chạy. Stable resolve tag cùng version đó thành commit SHA trước khi cài Pi package.
+
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, dùng tag cố định:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent@vX.Y.Z
+```
+
+Máy cá nhân/sandbox có thể theo moving source nếu chấp nhận cập nhật nhanh:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent
+```
+
+## Update và rollback cho team
+
+Full update phải đồng bộ exact Pi host trước, sau đó terminal helper và Pi package matching:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+piagent-install --stable --dry-run
+piagent-install --stable
+piagent-doctor /path/to/project --strict-share
+```
+
+Full rollback dùng cùng sequence với `vPREVIOUS`, nhưng exact Pi host phải lấy từ release policy của target và dependency risk phải được đánh giá lại trước khi hạ host. `piagent-install --version vX.Y.Z --resolve-tag` chỉ đổi Pi package, không đổi Pi host hay npm-global helper. Checklist chi tiết nằm tại [release/install policy](release-install-policy.md).
+
+Nếu team publish npm private:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+pi install npm:@your-scope/platform@x.y.z
+```
+
+Không cần chạy bash để set profile cho từng project.
+
+## Bước 2 — mở project và login OAuth
+
+```bash
+cd /path/to/project
+pi
+/login
+```
+
+Credential nằm trong user Pi dir, không commit.
+
+## 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.
+
+```text
+/model          # hoặc Ctrl+L
+/scoped-models  # optional
+```
+
+Global setup seed sẵn `enabledModels`; đổi nhanh bằng:
+
+```text
+Ctrl+P       # cycle scoped models
+Shift+Tab    # cycle thinking level
+```
+
+Rồi chạy:
+
+```text
+/mcp
+/subagents-doctor
+/onboard-project
+```
+
+Output chính:
+
+- `.pi/project-context.md`
+- `.pi/context-index.json`
+- `.pi/piagent-profile.json`
+- `.pi/piagent-profile.lock.json`
+- `.pi/tech-stack.json`
+- `.pi/tech-context/*.json`
+- `.pi/piagent-state/project-onboarding.json`
+
+Memory files are created locally but ignored by default:
+
+- `.pi/memory/memory_summary.md`
+- `.pi/memory/MEMORY.md`
+
+Đây là bước model đọc qua project lần đầu theo cách bounded: đọc profile, AGENTS, README, docs/config/source map/test command; không load toàn bộ source.
+
+Nếu project chưa có profile/tech stack, dùng select-style flow để tránh agent trả lời dài:
+
+```text
+/profile setup
+/profile tech setup fullstack
+```
+
+`fullstack` bắt chọn frontend, backend và database. Nếu native select chưa có trong Pi host, command trả card compact kèm lệnh deterministic `/profile tech apply ...`.
+
+Nếu `.pi/project-context.md` còn `Generated: not yet`, không nên chạy `/task` implementation.
+
+Memory mặc định là project-scoped và explicit-only. Chạy `/memory-policy` để xem files/rules. Agent chỉ ghi durable memory khi user yêu cầu rõ ràng.
+
+Đổi profile sau này:
+
+```text
+/profile list
+/profile setup
+/profile tech setup
+/profile fullstack
+/profile be-readonly-fe
+```
+
+## Setup nâng cao — tách global và project
+
+Các script setup/init vẫn tồn tại cho case preseed config vào repo hoặc CI bootstrap, nhưng không phải default UX:
+
+```bash
+bash /path/to/piagent/scripts/setup.sh /path/to/project \
+  --profile be-readonly-fe \
+  --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z \
+  --mcp-preset core \
+  --subagents-preset safe
+```
+
+Nếu cần override profile:
+
+```bash
+bash /path/to/piagent/scripts/setup.sh /path/to/project --project-only --profile backend-api --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z --mcp-preset core --subagents-preset safe
+```
+
+Profile built-in trong Pi:
+
+- `auto`: tự detect.
+- `generic`: repo chưa chuẩn.
+- `web-frontend`: Next/React/Vite frontend.
+- `backend-api`: Node/Java/Python API.
+- `be-readonly-fe`: scout BE read-only, implement FE only.
+- `fullstack`: repo có cả frontend và backend.
+- `node-typescript`: Node/TS library/tooling.
+- `python`: Python app/library.
+- `data`: ETL/dbt/DVC/notebook/data pipeline.
+- `devops`: Docker/Terraform/K8s/GitHub Actions.
+- `mobile`: React Native/Flutter.
+- `docs`: docs portal/manual.
+
+Project init tạo:
+
+- `.pi/settings.json`
+- `.pi/piagent-profile.json`
+- `.pi/context-index.json`
+- `.mcp.json`
+- `.pi/mcp.json`
+- `.pi/memory/memory_summary.md`
+- `.pi/memory/MEMORY.md`
+- `.pi/.gitignore`
+- `AGENTS.md` nếu chưa có
+- `REVIEW_GUIDELINES.md` nếu chưa có
+
+Hai file memory ở trên là local/private mặc định theo `.pi/.gitignore`; chỉ commit nếu team opt-in sau review.
+
+## Bước 4 — run trong Herdr
+
+```bash
+herdr
+cd /path/to/project
+pi
+```
+
+Trong Pi, nếu project trust prompt hiện ra, chỉ approve khi đúng repo. Project trust cho phép Pi load `.pi/settings.json`, `.pi` resources và project extensions.
+
+Sau khi team đã hiểu repo và muốn giảm prompt trust cho từng lần chạy, dùng:
+
+```bash
+piagent-auto
+```
+
+Read-only auto-run cho scout/audit:
+
+```bash
+piagent-auto --read-only -p "Scout module mapping. Do not edit source."
+```
+
+Lệnh này wrap `pi --approve`; nó không bypass piagent guard.
+
+## Bước 5 — task workflow
+
+Requirement chưa rõ:
+
+```text
+/discuss Tạo plan cho feature X. Chưa implement.
+```
+
+Task rõ:
+
+```text
+/task Implement feature X. Follow project profile, protected paths, required context, exec policy, context budget, tool policy, verify, trace, and task gate.
+```
+
+Scout/audit read-only:
+
+```text
+/scout Scout payment FE mapping vs BE contract. Backend read-only. Do not edit source.
+```
+
+Session nặng hoặc context overflow:
+
+```text
+/fresh-scout <read-only scout>
+/fresh-task <bounded task>
+/fresh-be-to-fe <BE-readonly/FE request>
+```
+
+Không paste full mandatory flow hằng ngày. Platform prompts/tools đã chứa checklist; input guard sẽ tự collapse boilerplate nếu paste nhầm.
+
+Runtime gate tools:
+
+```text
+piagent_exec_policy_check
+piagent_context_budget
+piagent_tool_policy_check
+piagent_task_gate_check
+```
+
+Task cải tiến platform:
+
+```text
+/platform-improve Improve onboarding, model scope, MCP setup, and verification docs for team usage.
+```
+
+Task BE spec lên FE:
+
+```text
+/be-to-fe Implement FE from BE contract <endpoint/spec>. Backend is read-only.
+```
+
+Project memory:
+
+```text
+/memory-policy
+Remember: this repo uses pnpm, never npm.
+```
+
+External source repo:
+
+```text
+Use piagent_source_checkout for github.com/org/repo, inspect only relevant files, then summarize applicable patterns.
+```
+
+## Doctor
+
+Chạy trên platform:
+
+```bash
+bash scripts/verify-local.sh
+```
+
+Chạy trên project:
+
+```bash
+bash /path/to/piagent/scripts/profile-doctor.sh /path/to/project
+bash /path/to/piagent/scripts/team-doctor.sh /path/to/project --strict-share
+bash /path/to/piagent/scripts/quality-benchmark.sh /path/to/project --init
+```
+
+Nếu doctor cảnh báo `project onboarding snapshot is still pending`, mở Pi trong project và chạy `/onboard-project`.
+
+## Không commit
+
+- `.pi/piagent-state/`
+- `.pi/benchmarks/`
+- `.pi/memory/local/`
+- `.pi/memory/state.sqlite`
+- `.pi/memory/rollout_summaries/`
+- `.pi/todos/`
+- `.pi/sessions/`
+- `.pi/auth.json`
+- `.env`
+- token/API key
+
+## Official docs
+
+- Pi packages: https://pi.dev/docs/latest/packages
+- Pi project trust/settings: https://pi.dev/docs/latest/settings
+- Pi prompt templates: https://pi.dev/docs/latest/prompt-templates
+- Pi MCP adapter: https://pi.dev/packages/pi-mcp-adapter
+- Herdr integrations: https://herdr.dev/docs/integrations/

package/docs/usage-observability.md

@@ -0,0 +1,130 @@
+# Usage observability
+
+Mục tiêu: biết Pi session đang tiêu hao token/context/cost như nào mà không phải hỏi model bằng ngôn ngữ tự nhiên.
+
+## Trong Pi TUI
+
+Pi có sẵn footer hiển thị token/cache usage, cost, context usage, model hiện tại. Khi cần chi tiết hơn, chạy:
+
+```text
+/session
+```
+
+Piagent package thêm command:
+
+```text
+/piagent-usage
+/task-preflight
+/task-preflight compact
+```
+
+Agent cũng có thể gọi tool:
+
+```text
+piagent_usage_snapshot
+piagent_context_preflight
+```
+
+`/piagent-usage` hiển thị:
+
+- session file;
+- session id/name;
+- cwd;
+- model;
+- live context usage hiện tại;
+- active branch entries / total entries;
+- lệnh để lấy exact token/cost totals từ terminal khác.
+
+`/task-preflight` hiển thị:
+
+- workflow đang định chạy;
+- live context;
+- estimated input tokens;
+- projected context;
+- recommendation: `ok`, `watch`, `compact`, hoặc `fresh-session`;
+- fresh workflow commands nếu session hiện tại quá nặng.
+
+`/task-preflight compact` gọi Pi compaction với hướng dẫn giữ lại decisions, blockers, changed files, verify command, và next action.
+
+Giới hạn kỹ thuật: extension command context expose `ctx.getContextUsage()`, phù hợp để biết context window đang dùng bao nhiêu. Exact billed totals như `input`, `output`, `cacheRead`, `cacheWrite`, `cost` là API của Pi `/session` và RPC `get_session_stats`.
+
+## Từ terminal khác
+
+Nếu đang có một Pi session chạy ở project khác, mở terminal mới:
+
+```bash
+piagent-usage /path/to/project
+```
+
+Hoặc dùng script trực tiếp:
+
+```bash
+bash scripts/pi-session-stats.sh /path/to/project
+```
+
+Script sẽ:
+
+1. tìm session `.jsonl` mới nhất có header `cwd` khớp project path;
+2. gọi Pi RPC `get_session_stats`;
+3. in JSON gồm messages, token totals, cost và context usage.
+
+Ví dụ output:
+
+```json
+{
+  "tokens": {
+    "input": 121095,
+    "output": 8088,
+    "cacheRead": 2023936,
+    "cacheWrite": 0,
+    "total": 2153119
+  },
+  "cost": 1.860083,
+  "contextUsage": {
+    "tokens": 102996,
+    "contextWindow": 272000,
+    "percent": 37.866176470588236
+  }
+}
+```
+
+## Cách đọc số
+
+| Field | Ý nghĩa |
+|---|---|
+| `input` | Token input thật gửi vào model. |
+| `output` | Token model sinh ra. |
+| `cacheRead` | Token đọc từ provider prompt cache. Số này có thể rất lớn nhưng không tương đương fresh input cost. |
+| `cacheWrite` | Token ghi vào cache. |
+| `total` | Tổng theo Pi stats. |
+| `cost` | Cost Pi tính theo pricing metadata của model/provider. |
+| `contextUsage.tokens` | Context window hiện đang bị chiếm bao nhiêu token. |
+| `contextUsage.percent` | Phần trăm context window hiện tại. |
+
+## Khi nào cần compact
+
+Xem `contextUsage.percent`:
+
+- `< 50%`: bình thường.
+- `50–70%`: bắt đầu tránh đọc file lớn không cần thiết.
+- `70–82%`: chạy `/task-preflight compact` trước task dài tiếp theo.
+- `> 82%`: dùng `/fresh-task`, `/fresh-scout`, hoặc `/fresh-be-to-fe` cho work mới.
+- Sau compaction, `contextUsage.tokens` có thể là `null` cho đến khi có assistant response mới.
+
+Nếu user paste full mandatory-flow boilerplate, platform input guard sẽ collapse về workflow command ngắn. Nếu prompt quá dài thật, platform có thể lưu intake vào `.pi/task-inbox/` local gitignored rồi replay bằng fresh workflow command.
+
+## Khi nào ghi benchmark
+
+Sau một task cần so sánh workflow/model bằng số liệu:
+
+```bash
+bash scripts/quality-benchmark.sh /path/to/project --record \
+  --scenario bounded-source-fix \
+  --surface pi \
+  --result pass \
+  --tokens <total-from-piagent-usage> \
+  --cost <cost-from-piagent-usage> \
+  --verify "<verify-command>"
+```
+
+Không dùng ước lượng ký tự để claim tiết kiệm token. Dùng `/session`, RPC `get_session_stats`, hoặc `piagent-usage`.

package/docs/vercel-docs-site.md

@@ -0,0 +1,115 @@
+# Vercel docs site
+
+## Khuyến nghị
+
+Giữ tài liệu HTML trong cùng repository, dưới `docs-site/`.
+
+Production URL: https://piagent.io.vn
+
+Vercel project: `pi-agent`
+
+Root Directory: `docs-site`
+
+Lý do:
+
+- docs đi cùng source và version của package;
+- source và docs được review trong cùng release candidate;
+- Vercel trỏ Root Directory thẳng vào `docs-site/`;
+- site static không cần build step hoặc environment secret.
+
+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.
+
+## Production promotion policy
+
+Production docs không được advertise một release tag chưa tồn tại.
+
+Luồng canonical:
+
+1. Sửa source và versioned docs trên release-candidate branch.
+2. Chạy verification và chờ CI pass.
+3. Tạo/push tag trên đúng verified commit và chờ tag-triggered CI trên Ubuntu/macOS pass.
+4. Chạy stable dry-run và xác nhận resolved commit SHA khớp tag.
+5. Sau đó release maintainer mới dùng bypass actor đã giới hạn trong ruleset để non-force fast-forward đúng tagged commit vào `main` (Vercel production branch), hoặc checkout đúng commit đó rồi chạy Vercel link preflight trước khi deploy `docs-site/`; không merge/squash/rebase, force-push hay chèn docs-only commit khác trong lúc promote.
+6. Kiểm tra live version, canonical URL, link và install command.
+
+Nếu Vercel đang auto-deploy production branch, giữ vNext docs ngoài branch đó cho tới khi tag CI + SHA verification hoàn tất. Checklist duy nhất nằm tại [release/install policy](release-install-policy.md).
+
+## Deploy bằng Dashboard
+
+1. Vào Vercel project `pi-agent`.
+2. Set Root Directory: `docs-site`.
+3. Set Framework Preset: `Other`.
+4. Build Command: để trống.
+5. Output Directory: `.` hoặc default.
+6. Chỉ promote production sau release gate ở trên.
+
+## Deploy bằng CLI
+
+Sau khi tag CI và stable SHA verification pass, từ checkout đúng tagged commit:
+
+```bash
+vercel link --cwd docs-site --project pi-agent
+npm run vercel:preflight
+vercel --cwd docs-site --prod
+```
+
+`npm run vercel:preflight` fail-closed nếu `.vercel/project.json` đang trỏ tới project cũ hoặc sai team. Không chạy production deploy bằng CLI trước khi preflight pass.
+
+Nếu CLI chưa đăng nhập:
+
+```bash
+vercel login
+```
+
+## Custom domain
+
+Canonical domain: `piagent.io.vn`
+
+Trong Vercel project `pi-agent` → Settings → Domains:
+
+- add `piagent.io.vn` và đặt làm **Primary**;
+- add `www.piagent.io.vn` và redirect về `piagent.io.vn`.
+
+Trong iNET DNS, dùng đúng record Vercel Domains panel đang hiển thị; không hardcode một IP cũ trong runbook:
+
+| Type | Name/Host | Value |
+|---|---|---|
+| `A` hoặc `ALIAS` theo Vercel | `@` | Exact apex target do Vercel hiển thị. |
+| `CNAME` | `www` | Exact CNAME target do Vercel hiển thị. |
+
+Không xoá `MX`, `TXT`, `NS`, hoặc email records nếu domain đang dùng mail. Sau khi DNS valid, Vercel sẽ cấp SSL tự động.
+
+Expected URL behavior:
+
+```text
+https://piagent.io.vn/      -> 200, không redirect
+https://www.piagent.io.vn/  -> redirect về https://piagent.io.vn/
+```
+
+Repo giữ canonical và Open Graph URL ở apex. Không đổi source sang `www` nếu hạ tầng vẫn được định hướng apex-primary.
+
+## Post-deploy verification
+
+```bash
+curl -I https://piagent.io.vn/
+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.
+
+## Local preview
+
+```bash
+cd docs-site
+python3 -m http.server 4173
+```
+
+Mở `http://localhost:4173`.
+
+## Security notes
+
+- Không đặt secret, token, auth file hoặc session cache trong `docs-site/`.
+- `docs-site/vercel.json` chỉ chứa static headers và URL behavior.
+- Không cần environment variable cho site tĩnh.
+- `.vercel/project.json` là metadata local bị ignore; luôn relink và chạy preflight trên checkout/máy deploy thay vì tin state còn sót lại.

package/docs/workflow-recipes.md

@@ -0,0 +1,125 @@
+# Workflow recipes
+
+## Mục tiêu
+
+Các recipe này biến những bài toán lặp lại thành workflow có tên rõ, dùng được cho project khác mà không phụ thuộc một project nội bộ cụ thể.
+
+## Recipe 1 — Platform improvement
+
+Dùng khi muốn cải tiến setup, prompt, MCP, model scope, memory, runtime policy, hoặc subagent workflow của Pi Agent Platform.
+
+Lệnh trong Pi:
+
+```text
+/onboard-project
+/platform-improve Improve <target behavior> in <platform area>.
+```
+
+Input tối thiểu:
+
+- source docs URL hoặc repo URL nếu task cần external context;
+- version/date/commit nếu có external context;
+- target behavior cần áp dụng;
+- non-goals: phần không làm trong scope này.
+
+Output mong đợi:
+
+- implementation matrix;
+- code/docs/config thay đổi;
+- verify evidence;
+- phần không làm và lý do.
+
+Verify chuẩn:
+
+```bash
+bash scripts/verify-local.sh
+bash scripts/team-doctor.sh /path/to/piagent --strict-share
+pi list --approve
+```
+
+Memory note:
+
+- Nếu task tạo decision/lesson bền vững, user có thể yêu cầu `Remember: ...`.
+- Agent dùng `piagent_memory_note` để ghi note explicit.
+- Không tự ghi toàn bộ transcript vào memory.
+- Nếu task tạo context điều hướng bền vững cho repo, dùng `piagent_context_index_record` để ghi node/edge/citation ngắn sau khi đã verify.
+
+## Recipe 2 — Backend spec to frontend
+
+Dùng khi backend là source of truth nhưng frontend là nơi implement. Backend chỉ được scout/read-only.
+
+Setup project generic:
+
+```text
+/profile list
+/profile be-readonly-fe
+```
+
+Lệnh trong Pi:
+
+```text
+/onboard-project
+/be-to-fe Implement FE from BE spec: <endpoint/spec/change>
+```
+
+Input tối thiểu:
+
+- BE endpoint/spec/diff/ticket;
+- expected FE behavior;
+- target route/page/component nếu biết;
+- verify expectation.
+
+Agent phải làm:
+
+1. Scout BE read-only.
+2. Ghi contract snapshot.
+3. Map FE touchpoints.
+4. Implement FE only.
+5. Verify FE.
+6. Report BE gaps thay vì sửa BE.
+
+## Khi dùng profile nào
+
+| Bài toán | Profile khuyến nghị |
+|---|---|
+| Platform/package/runtime improvement | `platform-development` hoặc profile platform riêng |
+| Fullstack bình thường, FE/BE đều có thể sửa | `fullstack` |
+| BE source of truth nhưng BE không được sửa | `be-readonly-fe` |
+| Backend-only task | `backend-api` |
+| Frontend-only task | `web-frontend` |
+| Project đặc thù/private | profile explicit trong chính repo project |
+
+Không dùng `auto` để suy ra `be-readonly-fe`, vì BE read-only là policy decision chứ không phải marker kỹ thuật.
+
+## Recipe 3 — Project memory
+
+Dùng khi muốn Pi nhớ durable facts/decisions/preferences giữa các session mà không phải scout lại từ đầu.
+
+```text
+/memory-policy
+Remember: this repo uses pnpm, never npm.
+```
+
+Rule:
+
+1. Memory là hint, không phải authority.
+2. Chỉ ghi explicit note khi user yêu cầu rõ.
+3. Không lưu secret/raw private data/source excerpt dài.
+4. Trước source edit, search memory nếu task liên quan rồi verify bằng repo file hiện tại.
+
+## Recipe 4 — Context index
+
+Dùng khi muốn giảm scout lại giữa các session mà không bật auto memory.
+
+```text
+/onboard-project
+/context-index
+/context-index search auth
+```
+
+Rule:
+
+1. Context index là advisory map, không phải source of truth.
+2. Node/edge phải ngắn và có citation tới file/doc/task đã verify.
+3. Không lưu raw transcript, secret, token, session, hoặc source excerpt dài.
+4. Nếu index stale so với profile/tech/onboarding snapshot, chạy lại `/onboard-project` hoặc record lại bằng `piagent_context_index_record`.