@piagent/platform 1.0.0

package/docs/distribution-standard.md

@@ -0,0 +1,229 @@
+# Distribution standard
+
+## Nguyên tắc
+
+Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậy:
+
+- default adapter không chứa domain riêng;
+- `.pi/settings.json` trong project phải dùng package source portable: `git:` hoặc `npm:`;
+- local absolute path chỉ dùng khi dev platform;
+- OAuth, trust, sessions, cache, piagent-state không commit;
+- project-specific/private profiles không nằm trong default `adapters/`.
+
+## Package source chuẩn
+
+| Use case | Package source |
+|---|---|
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.0.0` |
+| Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
+| Enterprise npm | `npm:@your-scope/platform@x.y.z` |
+| Local platform dev | `/path/to/piagent` |
+
+Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commit cho `.pi/settings.json` trong project nghiêm túc để tránh workflow đổi bất ngờ giữa các developer.
+
+## Release/install channels
+
+| Channel | Command | Target | Policy |
+|---|---|---|---|
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.0.0` | Install the Pi package matching the helper. |
+| `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
+| `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
+| `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
+
+Always preview non-local rollout first:
+
+```bash
+bash scripts/install-global.sh --stable --dry-run
+bash scripts/install-global.sh --version vX.Y.Z --resolve-tag --dry-run
+```
+
+Stable and resolved exact installs fail closed when the release tag cannot be resolved from GitHub. The install output prints the tag, resolved commit, and final `git:` package source before running `pi install`.
+
+`currentRelease` trong output là version của npm-global helper đang chạy. `--version` chỉ đổi Pi package; nó không tự thay binary `piagent-*` trên `PATH`.
+
+## Repo root là Pi package
+
+Root `package.json` có `pi` manifest trỏ tới:
+
+- `packages/piagent-core/extensions/piagent-guard.ts`
+- `packages/piagent-core/skills`
+- `packages/piagent-core/prompts`
+
+Do đó team có thể:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent@v1.0.0
+```
+
+Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
+
+## Default team setup
+
+Team nên install global package một lầ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 --dry-run
+piagent-install --stable
+```
+
+`pi install git:github.com/Vt-mmm/piagent@v1.0.0` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts github:Vt-mmm/piagent#v1.0.0`.
+
+Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
+
+Sau đó project nào cũng:
+
+```bash
+cd /path/to/project
+pi
+```
+
+Project profile được chọn trong Pi bằng `/onboard-project` hoặc `/profile`, không bắt buộc chạy bash init.
+
+Sau setup, bước first-run trong Pi là:
+
+```text
+/login
+<select provider/model>
+/mcp
+/subagents-doctor
+/onboard-project
+```
+
+`/onboard-project` ghi `.pi/project-context.md`; đây là snapshot context dùng chung cho các task sau.
+Nó cũng ghi `.pi/context-index.json`; đây là compact advisory map có citation để agent tìm đúng điểm vào repo mà không scout rộng lại.
+
+## Optional preseed setup
+
+Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap bằng CI:
+
+```bash
+bash scripts/setup.sh /path/to/project \
+  --profile be-readonly-fe \
+  --package-source git:github.com/Vt-mmm/piagent@v1.0.0 \
+  --mcp-preset core \
+  --subagents-preset safe
+```
+
+Với project cần scout BE nhưng chỉ implement FE, có thể chọn trong Pi:
+
+```text
+/profile be-readonly-fe
+```
+
+## Project init output
+
+`scripts/setup.sh` hoặc `scripts/init-project.sh` tạo scaffold project:
+
+```text
+project/
+├─ AGENTS.md
+├─ .gitignore
+├─ REVIEW_GUIDELINES.md
+├─ .mcp.json
+└─ .pi/
+   ├─ settings.json
+   ├─ piagent-profile.json
+   ├─ project-context.md
+   ├─ context-index.json
+   ├─ memory/
+   │  ├─ memory_summary.md
+   │  └─ MEMORY.md
+   ├─ mcp.json
+   └─ .gitignore
+```
+
+Files nên commit:
+
+- `AGENTS.md`
+- `.gitignore`
+- `REVIEW_GUIDELINES.md`
+- `.mcp.json`
+- `.pi/settings.json`
+- `.pi/piagent-profile.json`
+- `.pi/project-context.md`
+- `.pi/context-index.json`
+- `.pi/mcp.json`
+- `.pi/.gitignore`
+
+Files không commit:
+
+- `.pi/piagent-state/`
+- `.pi/task-inbox/`
+- `.pi/benchmarks/`
+- `.pi/memory/memory_summary.md`
+- `.pi/memory/MEMORY.md`
+- `.pi/memory/local/`
+- `.pi/memory/state.sqlite`
+- `.pi/memory/raw_memories.md`
+- `.pi/memory/rollout_summaries/`
+- `.pi/memory/extensions/ad_hoc/`
+- `.pi/sessions/`
+- `.pi/todos/`
+- `.pi/auth.json`
+- `.env`
+- `.pi-subagents/`
+- `progress.md` nếu chỉ là scratch runtime
+
+## Release, update và rollback
+
+[Release/install policy](release-install-policy.md) là checklist canonical duy nhất. Production docs chỉ được promote sau khi tag đã tồn tại và stable dry-run resolve đúng commit SHA.
+
+Full platform update phải đồng bộ Pi host, npm-global helper và Pi package:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1
+npm install -g --ignore-scripts github:Vt-mmm/piagent#vX.Y.Z
+piagent-install --stable --dry-run
+piagent-install --stable
+piagent-doctor /path/to/project --strict-share
+```
+
+Full rollback dùng cùng flow với target trước đó. Lấy exact host version từ release policy của target; không giả định host hiện tại tương thích với release cũ:
+
+```bash
+TARGET_PI_VERSION=x.y.z
+npm install -g --ignore-scripts "@earendil-works/pi-coding-agent@$TARGET_PI_VERSION"
+npm install -g --ignore-scripts github:Vt-mmm/piagent#vPREVIOUS
+piagent-install --stable --dry-run
+piagent-install --stable
+piagent-doctor /path/to/project --strict-share
+```
+
+Nếu chủ ý chỉ đổi Pi package và giữ terminal helper hiện tại:
+
+```bash
+piagent-install --version vX.Y.Z --resolve-tag --dry-run
+piagent-install --version vX.Y.Z --resolve-tag
+```
+
+## Security review
+
+Pi packages run with full system access. Before team rollout:
+
+- review every extension file;
+- no network call during startup;
+- network only inside explicit tools;
+- no secret logging;
+- destructive bash blocked;
+- project local profile loaded only after Pi trust or explicit env override.
+
+## Herdr standard
+
+Herdr integration is user-local:
+
+```bash
+herdr integration install pi
+```
+
+Do not assume Herdr is running. Scripts must degrade cleanly.
+
+## Official docs
+
+- Pi packages: https://pi.dev/docs/latest/packages
+- Pi settings/project trust: https://pi.dev/docs/latest/settings
+- Pi extensions/dependencies: https://pi.dev/docs/latest/extensions
+- Pi MCP adapter: https://pi.dev/packages/pi-mcp-adapter
+- Herdr integrations: https://herdr.dev/docs/integrations/

package/docs/herdr-workflow.md

@@ -0,0 +1,58 @@
+# Herdr workflow
+
+## Mục tiêu
+
+Herdr dùng để quản lý nhiều session/pane agent. Pi core không cần tự làm subagent ngay từ đầu.
+
+## Setup integration
+
+```bash
+herdr integration install pi
+herdr integration status
+```
+
+Nếu dùng custom Pi agent dir:
+
+```bash
+PI_CODING_AGENT_DIR=/path/to/pi-agent herdr integration install pi
+```
+
+## Daily flow
+
+```bash
+cd <project>
+herdr
+```
+
+Lần đầu trong project, mở pane Pi rồi chạy:
+
+```text
+/login
+<select provider/model>
+/onboard-project
+```
+
+Sau khi `.pi/project-context.md` đã được ghi, mới chạy `/task` cho implementation.
+
+Pane đề xuất:
+
+```text
+project
+├─ pi-task          implement current task
+├─ pi-review        read-only review
+├─ pi-qa            verify/test
+└─ pi-notes         decisions, handoff, and follow-up
+```
+
+## Rule
+
+- Herdr là orchestrator terminal/session, không phải security boundary.
+- Destructive/action gate vẫn nằm ở Pi extension/policy.
+- OAuth vẫn login trong Pi.
+
+## Nguồn
+
+- Herdr install: https://herdr.dev/docs/install/
+- Herdr integrations: https://herdr.dev/docs/integrations/
+- Herdr workflow: https://herdr.dev/docs/how-to-work/
+- Herdr CLI reference: https://herdr.dev/docs/cli-reference/

package/docs/mcp-and-tools.md

@@ -0,0 +1,316 @@
+# MCP và tool policy
+
+## Kết luận hiện tại
+
+Pi core không hard-code MCP. Platform của mình cài `pi-mcp-adapter` để Pi dùng MCP theo kiểu token-efficient: một proxy tool `mcp(...)`, server lazy-connect, metadata cache, output guard. Project profile chỉ khai báo capability được phép; MCP config mới khai báo server thật.
+
+Từ `v0.3.7`, repo có thêm:
+
+- `piagent-mcp` / `scripts/configure-mcp.sh`;
+- MCP preset `core`, `popular`, `all`, `design`, `design-local`, `browser`, `docs`, `github`;
+- template `.mcp.json` project-shared;
+- doctor warning khi adapter có nhưng không có MCP server nào.
+
+## Cấu hình một lần cho máy cá nhân/team
+
+Global install mặc định sẽ cài adapter và seed preset `core` nếu dùng `scripts/setup.sh` hoặc `scripts/install-global.sh --with-mcp`:
+
+```bash
+bash /path/to/piagent/scripts/setup.sh . \
+  --profile auto \
+  --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z \
+  --mcp-preset core
+```
+
+Chỉnh MCP sau này:
+
+```bash
+piagent-mcp --preset popular --scope global --replace
+piagent-mcp --preset design --scope global --replace
+piagent-mcp --preset all --scope project --project /path/to/project
+piagent-mcp --list
+```
+
+Nếu clone repo GitHub và chưa link npm bin:
+
+```bash
+bash /path/to/piagent/scripts/configure-mcp.sh --preset popular --scope global --replace
+```
+
+`--replace` cập nhật các server ID thuộc preset về baseline đã pin và vẫn giữ nguyên server ID khác. Luồng install/upgrade toàn cục luôn dùng chế độ này để không duy trì dependency động từ cấu hình cũ.
+
+Trong Pi:
+
+```text
+/mcp
+/mcp setup
+/mcp tools
+/mcp reconnect
+/mcp-auth figma
+```
+
+## MCP config layers
+
+Theo `pi-mcp-adapter`, thứ tự config nên giữ như sau:
+
+| File | Scope | Nên dùng khi nào |
+|---|---|---|
+| `~/.config/mcp/mcp.json` | shared global MCP config | mặc định cho nhiều agent/client và nhiều project |
+| `~/.pi/agent/mcp.json` | Pi global override | chỉ khi cần override riêng cho Pi |
+| `.mcp.json` | project shared MCP config | config server đặc thù repo, có thể commit |
+| `.pi/mcp.json` | Pi project override | override riêng Pi trong một repo |
+
+Quy ước của platform:
+
+- global baseline viết vào `~/.config/mcp/mcp.json`;
+- project baseline viết vào `.mcp.json`;
+- `.pi/mcp.json` để override Pi-specific, không nhét secret;
+- token strategy mặc định: `directTools: false`, dùng proxy `mcp(...)`;
+- chỉ bật `directTools` cho server nhỏ hoặc tool thật sự dùng thường xuyên.
+
+## Preset MCP
+
+| Preset | Server | Mục đích |
+|---|---|---|
+| `minimal` | none | chỉ seed settings an toàn |
+| `docs` | Context7 | docs mới của framework/library |
+| `browser` | Chrome DevTools, Playwright | inspect UI/runtime/browser automation |
+| `github` | GitHub MCP | issue/PR/repo/release workflow |
+| `design` | Figma remote | design-to-code qua Figma OAuth |
+| `design-local` | Figma desktop | Figma desktop Dev Mode MCP local |
+| `web` | Context7, Chrome DevTools, Playwright | FE/web workflow |
+| `core` | Context7, Chrome DevTools, GitHub | default team baseline |
+| `popular` | core + Playwright + Figma remote | baseline nhiều team dev dùng |
+| `all` | popular + Figma desktop | đầy đủ, dùng khi muốn sẵn cả local Figma |
+
+## Server baseline
+
+### Context7
+
+MCP config:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@3.2.4"],
+      "env": {
+        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
+      },
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+Khuyến nghị cho Pi: có thể cài thêm Pi-native package nếu muốn tool/docs tự nhiên hơn MCP:
+
+```bash
+pi install npm:@upstash/context7-pi@0.1.1
+```
+
+API key là optional nhưng nên dùng cho quota tốt hơn:
+
+```bash
+export CONTEXT7_API_KEY=ctx7sk_...
+```
+
+### Figma
+
+Remote MCP:
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp",
+      "auth": "oauth",
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+Local desktop MCP:
+
+```json
+{
+  "mcpServers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp",
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+Khuyến nghị thực tế:
+
+- dùng remote Figma MCP khi account/org hỗ trợ OAuth;
+- dùng desktop local khi cần selection-based Dev Mode trong app Figma;
+- nếu muốn Pi-native thay vì MCP, có thể cài `pi install npm:pi-mono-figma@0.2.2` sau khi hoàn tất security và license review.
+
+### Browser
+
+Chrome DevTools:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@1.6.0", "--no-performance-crux"],
+      "env": {
+        "CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS": "1",
+        "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"
+      },
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+Playwright:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.78"],
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+### GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "-e",
+        "GITHUB_READ_ONLY=1",
+        "-e",
+        "GITHUB_LOCKDOWN_MODE=1",
+        "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      "lifecycle": "lazy",
+      "directTools": false
+    }
+  }
+}
+```
+
+Token không được commit:
+
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
+```
+
+Preset mặc định chạy GitHub MCP ở read-only và lockdown mode. Bất kỳ cấu hình write nào cũng phải được tách riêng, giới hạn credential và yêu cầu human confirmation.
+
+## Tool policy
+
+Runtime tool registry nằm trong `packages/piagent-core/policies/base-policy.json`.
+
+Tool:
+
+```text
+piagent_tool_policy_check
+```
+
+Default `toolRegistry=advisory`: agent nhận warning khi tool chưa map capability. Project ổn định có thể bật `toolRegistry=enforce` trong `.pi/piagent-profile.json`.
+
+Protected-path gate độc lập với registry mode. Dù tool registry đang `advisory`, mọi raw tool call có path-like string trỏ vào protected path sẽ bị block trước khi tool chạy. Cơ chế này áp dụng cho Pi built-ins (`read`, `write`, `edit`, `grep`, `find`, `ls`) và custom/MCP tools nếu tool call đi qua Pi `tool_call` hook.
+
+Extractor walk nested object/array và `file://` URI. Path-like string được percent-decode một lần trước khi match. Field lạ mặc định được coi là path-like; chỉ leaf field nội dung đã biết như `content`, `query`, `pattern`, `text`, và `command` được skip để tránh false positive search/edit. Input lồng quá sâu vượt `MAX_TOOL_INPUT_INSPECTION_DEPTH=32` sẽ fail-closed.
+
+Search/list channels cũng được kiểm:
+
+- `grep.glob` bị block nếu glob nhắm protected path rõ ràng như `.env*`, `auth.json`, `.pi/piagent-state/**`, hoặc `piagent-profile.json`;
+- `find.pattern` bị block nếu pattern nhắm protected path rõ ràng;
+- broad pattern như `*.json` được phép để không phá search workflow phổ biến;
+- broad `grep/find/ls` được phép chạy khi không target trực tiếp, nhưng `tool_result` sẽ redact content line hoặc path metadata từ protected files trước khi model thấy output.
+
+| Mode | Allowed intent |
+|---|---|
+| `readOnly` | đọc file, grep, find, list, MCP read-only |
+| `memory` | đọc/search memory, ghi note explicit-only |
+| `docsWrite` | sửa docs/plans/report |
+| `sourceWrite` | sửa source theo protected path + verify |
+| `ship` | release/commit/push/deploy, cần human gate |
+
+## Rule bắt buộc
+
+- Capability chưa đăng ký: clean skip, không tự đoán tool.
+- Tool destructive: block hoặc hỏi xác nhận.
+- Tool external-provider: hỏi xác nhận nếu có side effect/cost.
+- MCP response phải ngắn; server tự build phải có concise/detailed mode.
+- Memory tool không được lưu secret/raw private data; memory là advisory, source hiện tại là authority.
+- Không commit token/API key/OAuth file.
+- Không bật `directTools: true` đại trà cho server lớn; sẽ phá lợi thế token của Pi.
+
+## Built-in platform tools
+
+| Tool | Intent |
+|---|---|
+| `piagent_context` | Active profile/context/verify/MCP/memory overview. |
+| `piagent_exec_policy_check` | Evaluate shell command before running. |
+| `piagent_context_budget` | Check candidate context files against hard caps. |
+| `piagent_tool_policy_check` | Check tool capability registration. |
+| `piagent_task_gate_check` | Check task readiness before final DONE. |
+| `piagent_memory_status` | Project memory policy/files/rules. |
+| `piagent_memory_search` | Keyword search `.pi/memory` markdown. |
+| `piagent_memory_note` | Append explicit durable memory note. |
+| `piagent_memory_citation_record` | Record memory evidence in task contract. |
+| `piagent_context_index_status` | Inspect the compact advisory project context index. |
+| `piagent_context_index_search` | Search context-index nodes before broad re-scouting. |
+| `piagent_context_index_record` | Record cited project/profile/tech/task context after onboarding or approved handoff. |
+| `piagent_profile_options` | Return reusable project profile choices. |
+| `piagent_profile_apply` | Apply a selected profile and deterministic capability lock. |
+| `piagent_profile_tech_options` | Return select-style tech options for a profile family. |
+| `piagent_profile_tech_apply` | Apply profile + selected role tech stack and Context7 placeholders. |
+| `piagent_profile_tech_context_record` | Record a concise Context7 evidence snapshot for a selected tech. |
+| `piagent_task_start` | Create Task Implementation Contract. |
+| `piagent_context_record` | Record context manifest for task. |
+| `piagent_verify_record` | Record verify evidence only when it matches an observed Pi bash result after task start. Passing gate also requires exact match with `task.verifyCommands`. |
+| `piagent_trace_record` | Record handoff/final trace. |
+
+## Core capabilities
+
+| Capability | Meaning |
+|---|---|
+| `filesystem-readonly` | Read/list/search repository files. |
+| `filesystem-write` | Edit/write non-protected project files. |
+| `shell` | Run shell commands through exec policy. |
+| `github` | GitHub/MCP/CLI workflows when configured. |
+| `browser` | Browser/UI/runtime inspection when configured. |
+| `memory` | Project memory tools. |
+
+## Nguồn
+
+- Pi MCP adapter: https://pi.dev/packages/pi-mcp-adapter
+- Context7 Pi package: https://pi.dev/packages/@upstash/context7-pi
+- Figma remote MCP docs: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+- Figma desktop MCP docs: https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+- GitHub MCP server: https://github.com/github/github-mcp-server
+- MCP protocol: https://modelcontextprotocol.io/
+- Pi extension tool events: https://pi.dev/docs/latest/extensions