pan-stack-cli 0.1.4 → 0.2.1

package/README.md

@@ -40,12 +40,12 @@ skill pre-installed for all three agent folders.
 ## Requirements
 
 - Node.js 18+
-- Git (for `pan clone`, `pull`, `fetch`, `push`, `grv`, `gst`)
+- Git (for `pan clone`, `pull`, `sync-main`, `fetch`, `push`, `grv`, `gst`, `stats`)
 
 ## Windows support
 
-Built-in commands (`create`, `clone`, `pull`, `push`, `fetch`, `grv`, `gst`) run on
-Windows, macOS, and Linux. Notes for Windows:
+Built-in commands (`create`, `clone`, `pull`, `sync-main`, `push`, `fetch`, `mr`, `checkout`,
+`grv`, `gst`) run on Windows, macOS, and Linux. Notes for Windows:
 
 - `shell:` blocks in `.pan.yaml` run through **bash** on all platforms (Git Bash on
   Windows, system bash on macOS/Linux). Use `exec:` for simple one-liners (`npm test`)
@@ -72,14 +72,236 @@ pan install
 
 `pan create` fails if the target folder already exists.
 
+**Cần registry server**: scaffold template (`workspace`) không còn bundle sẵn trong
+`pan-stack-cli` — `pan create` tải template qua `apps/pan-agent-skill-registry`
+(`PAN_SKILL_REGISTRY_URL`, mặc định `http://localhost:4600`), giống cơ chế
+`pan ai install`. Server không chạy được → `pan create` báo lỗi rõ, không scaffold
+được (không có fallback local).
+
+## Agent skills — `pan ai`
+
+Builtin (không cần khai báo trong `.pan.yaml`). Quét skill ở **workspace root**
+(thư mục chứa `.project.yaml`): `.claude/skills`, `.cursor/skills`, `.codex/skills`.
+Gộp theo tên skill — bật/tắt đồng bộ cả ba agent folder. Disable đổi tên
+`SKILL.md` → `SKILL.md.disabled` (và `AGENTS.md` tương tự); enable đổi ngược lại.
+
+```bash
+pan ai                         # tương tác: Disable | Enable | List | Install | Update
+pan ai --list                  # chỉ xem trạng thái
+pan ai --disable writing-guidelines
+pan ai --enable writing-guidelines
+pan ai --disable ux-audit --dry-run
+pan skills --list              # alias
+```
+
+> Menu tương tác của `pan ai` theo đúng [quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan):
+> `x` thoát ở mọi bước, `b` quay lại menu action từ bước chọn skill, `a`/`i` khi chọn nhiều skill.
+
+### Install / Update — cài & cập nhật skill/agent từ registry server
+
+Hai action mới trong menu `pan ai` gọi tới registry server (`apps/pan-agent-skill-registry`)
+để tải skill/agent đóng gói dạng zip:
+
+- **Install**: liệt kê package chưa cài (từ `GET {baseUrl}/api/registry`), cho chọn nhiều,
+  tự phát hiện agent dir sẵn có (`.claude`/`.cursor`/`.codex` đã tồn tại ở workspace root) để
+  cài luôn; nếu chưa có agent dir nào thì hỏi chọn agent đích trước khi cài. Nếu server báo có
+  bản cập nhật cho package đã cài, item đầu danh sách cho phép nhảy sang luồng Update.
+- **Update**: liệt kê package đã cài nhưng có version mới hơn, cho chọn (hoặc "Update all"),
+  tải lại đúng các agent dir đã cài trước đó (ghi trong lockfile).
+
+Config base URL bằng env `PAN_SKILL_REGISTRY_URL` (mặc định `http://localhost:4600`).
+Trạng thái "đã cài gì, version nào, cài vào agent dir nào" lưu ở
+`<workspaceRoot>/.pan/skills-lock.json` (không commit — thêm vào `.gitignore` nếu cần).
+
+Nếu chạy `pan ai` mà KHÔNG đứng trong 1 workspace pan-stack (không tìm thấy `.project.yaml`
+walk-up từ cwd) và đang ở TTY tương tác, CLI hỏi có muốn tạo dự án mới ngay tại thư mục hiện
+tại không — lựa chọn **"Không" luôn đứng trước "Có"** trong menu. Chọn "Có" thì tạo ngay
+`.project.yaml` (3 dòng: `project`, `language: vi`, `managed_by` lấy từ `git config user.name`
+
+- `user.email`, thiếu thì ghi `YourName`) rồi tiếp tục `pan ai` như đang ở trong workspace đó.
+
+## `pan language` (`pan lang`) — đổi ngôn ngữ CLI
+
+Danh sách ngôn ngữ available định nghĩa ở 2 nơi (đi cùng nhau khi thêm ngôn ngữ mới):
+
+- `lib/messages.js` — nguồn thật của **mã ngôn ngữ hợp lệ** (1 object con `en: {...}`,
+  `vi: {...}`, … — mỗi key là 1 message theo mã đó). `availableLangs()` (`lib/i18n.js`)
+  đọc `Object.keys(messages.js)`.
+- `lib/languages.js` — **tên hiển thị** cho mỗi mã (vd `vi` → "Tiếng Việt"), dùng bởi
+  menu `pan language`. Thiếu dòng ở đây thì menu vẫn hiện, chỉ dùng luôn mã thay tên.
+
+```bash
+pan language                  # menu tương tác: chọn ngôn ngữ (đánh dấu ngôn ngữ hiện tại)
+pan language vi                # đặt trực tiếp, không cần menu
+pan lang en                    # alias
+```
+
+Ghi `language: <mã>` vào `.project.yaml` gần nhất (walk-up từ cwd); chưa có key → thêm,
+đã có → cập nhật. Không có `.project.yaml` → `pan language <mã>` báo lỗi (cần workspace
+để lưu), còn `pan language` (xem/không đổi) vẫn chạy, dùng mã mặc định/env (`PAN_LANG`).
+
+Menu chọn ngôn ngữ theo đúng [quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan):
+`↑↓` di chuyển · gõ chữ nhảy tới item · `Enter` chọn (áp dụng ngay) · `b` quay lại (không đổi
+gì) · `x` thoát hẳn CLI.
+
+## `pan ui` — đồng bộ Pan Studio
+
+Đồng bộ dự án panui giữa **local ↔ Pan Studio backend**: đăng nhập, clone, đẩy thay
+đổi lên, publish HTML, sinh mã React.
+
+```bash
+pan ui                         # menu tương tác
+pan ui login                   # đăng nhập (mở trình duyệt, device-flow)
+pan ui logout                  # đăng xuất, xóa key local
+pan ui clone                   # tải dự án về local
+pan ui sync                    # đẩy thay đổi local → backend
+pan ui published-html          # publish trang HTML công khai
+pan ui gen-react-web-code      # sinh mã React web (.tar.gz)
+pan ui gen-react-mobile-code   # coming soon — chỉ in "Đang phát triển"
+```
+
+> Menu `pan ui` (chọn subcommand) và cascade 4 bước của `pan ui init` (Design System → loại →
+> template → bảng màu) theo [quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan): `x`
+> thoát mọi bước, `b` quay lại bước trước trong `pan ui init`.
+
+### `init` — tạo dự án panui mẫu
+
+Vì hiện có **2 design system**, bước đầu tiên của `pan ui init` luôn là **chọn Design
+System** — trước cả bước chọn loại/template/bảng màu:
+
+```
+? Chọn Design System:
+❯ shadcn ui (Recommended)
+  antd
+```
+
+- **`shadcn ui` (Recommended)** — đứng đầu danh sách, là lựa chọn mặc định.
+- **`antd`** — lựa chọn thứ hai.
+
+Sau khi chọn Design System, cascade tiếp tục như cũ: **loại** (Web landing / Mobile /
+CMS) → **template** → **bảng màu** → nhập tên/đường dẫn dự án. `b` quay lại bước trước
+(kể cả quay lại bước chọn Design System từ bước chọn loại), `x` thoát hẳn — theo
+[quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan).
+
+**Cần registry server**: các template pan-ui (landing-glass, mobile-app,...) không còn
+bundle sẵn — danh sách loại/template lấy từ `apps/pan-agent-skill-registry`
+(`PAN_SKILL_REGISTRY_URL`, mặc định `http://localhost:4600`); chỉ tải zip của
+ĐÚNG template user chọn (không tải hết). Server không chạy được → báo lỗi rõ.
+
+### `login` — đăng nhập (device-flow)
+
+Giống `claude` / `gh auth login`: không nhập user/password trong terminal. CLI gọi
+`POST /auth/device/start`, mở trình duyệt tại trang `/cli-auth` để đăng nhập + bấm
+"Approve" (fallback: dán URL tay nếu không tự mở được browser), rồi poll
+`/auth/device/poll` tới khi được duyệt. Key nhận về dạng `pmcp_...`, hạn dùng 90
+ngày, lưu tại `~/.pan/credentials.json` (quyền file `600`). Hết hạn → chạy lại
+`pan ui login`. (`pan ui init` vẫn chạy được như alias của `login`.)
+
+Đã có key **còn hạn** cho đúng `apiUrl` hiện tại → `pan ui login` KHÔNG tự chạy lại
+device-flow, chỉ in info (email + hạn dùng) và hướng dẫn:
+`pan ui logout` rồi `pan ui login` lại, hoặc `pan ui login --force` (`-f`) để
+đăng nhập lại ngay, ghi đè key hiện tại.
+
+### `logout`
+
+Xóa key local (`~/.pan/credentials.json`) cho API hiện tại. Token trên backend vẫn
+còn hạn — thu hồi ở UI/`me/mcp-tokens` nếu cần.
+
+### `clone`
+
+Chọn dự án theo danh sách lấy từ backend (key phải hợp lệ), sau đó hỏi **thư mục
+đích** (mặc định `pan-ui`). Nếu thư mục đã tồn tại → **báo lỗi, không tự xóa** —
+phải xóa thủ công rồi chạy lại. Tải toàn bộ cây file về local và ghi
+`backend: { id, apiUrl }` vào `app.panui.yaml` (định danh dự án dùng cho `sync`
+sau này).
+
+### `sync` — push local → backend
+
+Đọc `backend.id` trong `app.panui.yaml` (thiếu → gợi ý chạy `clone` trước). So
+sánh (diff) local với backend: file thêm / đổi / xóa. Trước khi đẩy sẽ:
+
+1. Hiện tên + id dự án và hỏi xác nhận **đúng dự án** (tránh đẩy nhầm).
+2. Hiện bảng diff và hỏi xác nhận **trước khi đẩy**.
+3. File xóa ở local → hỏi riêng trước khi xóa trên backend.
+
+Đây hiện là chiều **push-only** (local → backend); pull để sau.
+
+### `published-html` / `gen-react-web-code` — publish & sinh mã
+
+Cả hai đều **GATE bằng sync**: nếu local khác backend, CLI báo và hỏi sync ngay
+(hoặc dừng để bạn tự `pan ui sync`) trước khi build. Chỉ khi local đã khớp
+backend mới build tiếp.
+
+- `published-html`: gọi build HTML trên backend, chờ xong, in URL công khai
+  dạng `<apiUrl>/p/<prefix>`.
+- `gen-react-web-code`: gọi build React trên backend, chờ xong, tải `.tar.gz` và
+  giải nén vào thư mục đích (mặc định `pan-ui-react`; đã tồn tại → báo lỗi, không
+  tự xóa). Máy không có lệnh `tar` hệ thống → chỉ lưu file `.tar.gz` và in hướng
+  dẫn giải nén thủ công.
+- `gen-react-mobile-code`: chưa làm — chỉ in "Đang phát triển".
+
+Mỗi lần build tạo một `ExportVersion` mới trên backend (version bump); artifact
+build không đè lên file nguồn.
+
+### Cấu hình
+
+`PAN_STUDIO_API_URL` / `PAN_STUDIO_WEB_URL` — ưu tiên (cao → thấp):
+
+1. biến môi trường (`PAN_STUDIO_API_URL=...`)
+2. file `.pan-env-build.yaml` ở workspace root:
+   ```yaml
+   PAN_STUDIO_API_URL: http://localhost:3001
+   PAN_STUDIO_WEB_URL: http://localhost:3001
+   ```
+3. Trỏ về Pan Studio backend dev
+
+`PAN_STUDIO_WEB_URL` thiếu ở cả 3 mức trên thì lấy luôn giá trị `PAN_STUDIO_API_URL`
+đã resolve.
+
+### Monorepo — nhiều dự án panui
+
+`sync`/`published-html`/`gen-react-web-code` quét mọi `app.panui.yaml` từ
+`.project.yaml` root, tối đa **5 cấp** thư mục (bỏ qua `node_modules`, `.git`,
+`dist`). Tìm thấy nhiều dự án → hỏi chọn; chỉ 1 dự án → dùng luôn, không hỏi.
+
+> ⚠️ Lưu ý: block `.html` (liên kết html-ui) chỉ được đặt trong thư mục
+> `components/` của dự án panui.
+
+## Static server — `pan serve`
+
+Phục vụ một thư mục build tĩnh qua HTTP (SPA mode). Hữu ích để xem web demo do
+`pnpm panui:gen` (Pan Design System) sinh ra, hoặc bất kỳ thư mục `dist` nào.
+
+```bash
+pan serve <dir> [options]
+
+pan serve ./panui-demo            # → http://localhost:3000
+pan serve ./panui-demo -p 8080    # đổi cổng
+pan serve                          # phục vụ thư mục hiện tại
+```
+
+Options: `-p, --port <port>` (mặc định 3000) · `-h, --help`.
+
+Bọc package [`serve`](https://www.npmjs.com/package/serve) với cờ `-s` (single-page:
+route sâu / refresh vẫn trả `index.html`). Ưu tiên bản cài trong pan-stack-cli; nếu
+chưa cài thì tự chạy qua `npx serve` (tải lần đầu). Chạy trên Windows/macOS/Linux.
+
+Ví dụ luồng "build + xem" web demo panui:
+
+```bash
+# trong repo Pan Design System:
+pnpm panui:gen pan-design-system-markdown/examples/blog-project -o ./panui-demo
+pan serve ./panui-demo
+```
+
 ## Configuration files
 
 Two files drive the CLI. Keep responsibilities separate:
 
-| File | Role |
-|------|------|
+| File            | Role                                                                          |
+| --------------- | ----------------------------------------------------------------------------- |
 | `.project.yaml` | Workspace manifest — lists `repositories` (name, url, path). **No commands.** |
-| `.pan.yaml` | `pan` commands — at workspace root and/or inside each child repo |
+| `.pan.yaml`     | `pan` commands — at workspace root and/or inside each child repo              |
 
 ### `.project.yaml` example
 
@@ -101,6 +323,29 @@ repositories:
     path: apps/api
 ```
 
+### `.project.local.yaml` — repo riêng, không commit
+
+Muốn tự thêm repo riêng (thử nghiệm, fork cá nhân, repo nội bộ chỉ mình bạn cần…)
+mà không đụng `.project.yaml` chung của team? Tạo `.project.local.yaml` cùng thư
+mục — chỉ cần field `repositories:` (không cần `project:`/`stack:`/gì khác):
+
+```yaml
+# .project.local.yaml — KHÔNG commit (đã có trong .gitignore của 'pan create')
+repositories:
+  - name: my-experiment
+    url: https://github.com/you/my-experiment.git
+    path: apps/my-experiment
+```
+
+Mọi lệnh đọc `repositories` (`pan clone|pull|push|fetch|grv|gst|sync-main|mr|checkout`,
+`pan stats`, và cả danh sách lệnh `.pan.yaml` theo từng repo) tự động **gộp thêm**
+repo từ file này vào `.project.yaml` chung — không cần khai báo/sửa gì thêm ở
+nơi khác. Có repo local → mỗi lần chạy in 1 dòng gợi ý `ℹ️  +N repo từ
+.project.local.yaml` để bạn biết đang có repo riêng đang hoạt động.
+
+`pan create` scaffold sẵn `.gitignore` chứa dòng `.project.local.yaml` — workspace
+cũ (tạo trước khi có tính năng này) tự thêm dòng đó vào `.gitignore` của mình.
+
 ### `.pan.yaml` — workspace root
 
 Orchestration commands. Paths are relative to the workspace root. Use
@@ -150,18 +395,146 @@ commands:
 
 Aliases: `alias: i` or `aliases: i, ins` (comma-separated).
 
+### `sequence` — gom nhiều lệnh lẻ chạy TUẦN TỰ (vd "build all")
+
+Có nhiều lệnh `exec`/`shell` lẻ (build-fe, build-be, build-extension, …) trong CÙNG 1
+file `.pan.yaml`, muốn có thêm 1 lệnh "chạy tất cả theo thứ tự" mà không copy lại
+script? Khai báo field `sequence` (thay cho `exec`/`shell`) — mỗi dòng 1 bước, chạy
+đúng thứ tự viết, dừng ngay khi 1 bước lỗi:
+
+```yaml
+commands:
+  build-fe:
+    exec: pnpm --filter web build
+
+  build-be:
+    default: dev
+    targets:
+      dev:
+        exec: pnpm --filter api build:dev
+      prod:
+        exec: pnpm --filter api build:prod
+
+  build-extension:
+    shell: |
+      cd tools/vscode-pan-uispec && npm run package
+
+  build-all:
+    description: Build FE + BE(prod) + extension theo đúng thứ tự
+    sequence: |
+      build-fe
+      MODE=prod build-be:prod
+      build-extension?
+```
+
+Cú pháp 1 dòng: `[KEY=VAL ...] tênLệnh[:target][?]`
+
+- **`tênLệnh`** — phải là 1 command khác **đã khai báo trong cùng file `.pan.yaml`
+  này** (không gọi chéo sang `.pan.yaml` của repo khác).
+- **`:target`** — chọn target nếu lệnh đó có `targets:` (giống cách gọi `pan build-be prod`).
+- **`KEY=VAL ...`** (đặt trước tên lệnh) — biến môi trường chỉ áp dụng cho **riêng bước
+  đó**, không ảnh hưởng các bước khác hay sequence gọi nó.
+- **`?`** cuối tên lệnh — bước lỗi (exit code ≠ 0) chỉ in cảnh báo rồi **chạy tiếp**
+  bước sau, thay vì dừng cả sequence (mặc định KHÔNG có `?` = lỗi là dừng ngay, exit
+  code của sequence = exit code bước lỗi đó).
+- Cũng chấp nhận 1 dòng, phân tách bởi `,` khi không cần set biến: `sequence: build-fe, build-be`.
+- `pan build-all` chạy như 1 lệnh bình thường (không có tham số riêng cho sequence);
+  từng bước bên trong dùng target/biến đã khai báo sẵn trong `sequence:`.
+
+### Interactive select — chọn nhiều/một khi chạy lệnh
+
+Bất kỳ command nào (mọi stack: Node/Java/.NET…) khai báo `select*` → `pan` **render picker tương tác**
+(checkbox @inquirer, ⭐TẤT CẢ trên đỉnh) và truyền lựa chọn vào `shell`/`exec` qua **env `PAN_SELECTED`**
+(mỗi dòng 1 giá trị) + `PAN_SELECTED_COUNT`. Script chỉ là shell THUẦN — không cần thêm dependency.
+
+| Field           | Ý nghĩa                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `selectFrom`    | Lệnh shell; **mỗi dòng stdout = 1 choice** (`label<TAB>value` để đặt nhãn riêng). Vd `ls -1 *.yaml`, `oc get deploy -o name`. |
+| `selectChoices` | Danh sách tĩnh, phân tách bởi `,` hoặc newline (thay cho `selectFrom`).                                                       |
+| `selectMessage` | Câu hỏi hiển thị.                                                                                                             |
+| `selectMulti`   | `true` (mặc định, checkbox nhiều) · `false` (chọn một).                                                                       |
+| `selectAll`     | `true` (mặc định, thêm ⭐TẤT CẢ) · `false`.                                                                                   |
+
+`all` (arg) / `PAN_ALL=1` / non-TTY (CI) ⇒ **chọn hết** (bỏ qua picker). Không chọn gì ⇒ thoát.
+
+```yaml
+commands:
+  deploy:
+    description: "Apply manifest (chọn) — hoặc: pan deploy all"
+    selectMessage: "Chọn manifest apply:"
+    selectFrom: "ls -1 k8s/*.yaml"
+    shell: |
+      set -euo pipefail
+      while IFS= read -r f; do [ -n "$f" ] && kubectl apply -f "$f"; done <<< "${PAN_SELECTED:-}"
+```
+
+**Primitive `pan select`** — cho script chủ động bắt lựa chọn qua stdout (picker render trên stderr):
+
+```bash
+sel=$(pan select --multi --all --from "ls -1 k8s/*.yaml" --message "Chọn manifest:")
+for f in $sel; do kubectl apply -f "$f"; done
+# pan select --single a b c     # chọn một trong inline choices
+```
+
+### Quy ước chung cho MỌI menu tương tác trong `pan`
+
+Toàn bộ picker/menu trong CLI (menu gốc `pan` trống, `pan ai`, `pan ui`, `pan mr`, `pan checkout`,
+git repo picker, v.v.) đều dùng chung 2 prompt nội bộ `menuSelect`/`menuCheckbox`
+(`lib/menu-prompt.js`, cần `@inquirer/core`) và tuân theo cùng một bộ phím:
+
+| Phím             | Ý nghĩa                                                | Áp dụng                               |
+| ---------------- | ------------------------------------------------------ | ------------------------------------- |
+| `Enter`          | Xác nhận lựa chọn hiện tại                             | Mọi menu                              |
+| `↑`/`↓` + gõ chữ | Di chuyển / gõ nhảy tới item                           | Mọi menu                              |
+| `b`              | **Quay lại** menu cấp trước (không thoát chương trình) | Menu cấp con (sau khi đã chọn ≥1 cấp) |
+| `x`              | **Thoát hẳn** CLI (`process.exit(0)` sạch)             | Mọi menu, kể cả menu gốc              |
+| `space`          | Tick/bỏ tick 1 dòng                                    | Menu chọn nhiều (`menuCheckbox`)      |
+| `a`              | Chọn tất cả / bỏ chọn tất cả (toggle)                  | Menu chọn nhiều                       |
+| `i`              | Đảo chọn (invert)                                      | Menu chọn nhiều                       |
+
+Thiếu `@inquirer/core` (dep không cài) → mọi picker fallback sang `@inquirer/prompts`
+(`select`/`checkbox` thô) + thêm item ẩn ở cuối danh sách cho `b`/`x` (không phải hotkey nhấn-1-phím,
+nhưng vẫn chọn được bằng Enter) để giữ đúng hành vi quay lại/thoát dù thiếu dependency.
+
+Không có nơi nào trong CLI tự chế cách chọn riêng (loop `readline` tay chỉ còn là fallback CUỐI CÙNG
+khi thiếu cả `@inquirer/core` lẫn `@inquirer/prompts`). `pan ai`, `pan ui` (kể cả cascade
+loại→template→bảng màu của `pan ui init`), `pan mr`, `pan checkout` đều đã áp dụng quy ước này —
+nếu bạn thấy hành vi phím tắt khác trước đây (vd `pan mr`/`pan checkout` giờ có thêm `x` thoát ở
+bước chọn repo, `pan ui init` giờ có `b` quay lại giữa 3 bước chọn), đó là do đồng bộ theo quy ước
+chung này.
+
+## `pan git` — menu chọn lệnh git (đỡ nhớ tên/xem help dài)
+
+Các lệnh git ở dưới đây (clone/pull/push/fetch/sync-main/mr/checkout/grv/gst) và cả
+`stats` (cũng là 1 dạng thống kê Git từ log) nằm **rải rác** — không nhớ hết tên thì
+gõ `pan git` để xem menu chọn:
+
+```bash
+pan git            # TTY: menu tương tác chọn 1 lệnh git rồi chạy ngay (x thoát)
+                   # không TTY: in danh sách lệnh rồi thoát (không lỗi)
+pan git pull       # có sẵn tên → chạy thẳng, y hệt gõ 'pan pull' (chỉ là lối gõ khác)
+pan git -h         # in danh sách lệnh + mô tả
+```
+
+Đây chỉ là **lối vào phụ** (discoverability) — hành vi/tham số của từng lệnh (`--dry-run`,
+`--base-dir`, target tương tác…) không đổi gì so với gõ thẳng `pan <command>`.
+
 ## Built-in git commands
 
 Read `repositories` from the nearest `.project.yaml` (walk-up from cwd):
 
-| Command | Action |
-|---------|--------|
-| `pan clone` | Clone all repositories in the manifest |
-| `pan pull` | Pull all cloned repositories |
-| `pan fetch` | Fetch all remotes |
-| `pan push` | Push all repos (`-u origin HEAD` by default) |
-| `pan grv` | `git remote -v` for workspace + each child repo |
-| `pan gst` | `git status` for workspace + each child repo |
+| Command                                                       | Action                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pan clone`                                                   | Clone all repositories in the manifest — bảng tổng hợp `repo · result · note` (cloned · already exists · no access · not found · failed; KHÔNG dừng ở lỗi đầu tiên, clone hết rồi mới tổng hợp)                                                                                                                                |
+| `pan clone <git-url>`                                         | **Thêm 1 repo mới** — tự tách tên dự án từ URL (bỏ đuôi `.git`, lấy phần cuối path/scp-like), **ghi thêm entry vào `.project.yaml`** (path mặc định `apps/<tên>`), rồi clone ngay repo đó. Đã có tên đó trong manifest → dùng lại entry cũ, không thêm trùng. Xem [chi tiết](#pan-clone-url--thêm-repo-mới-tiện-như-git-clone) |
+| `pan pull`                                                    | Pull all cloned repositories — bảng tổng hợp `repo · branch · result · changes · conflict`                                                                                                                                                                                                                                     |
+| `pan sync-main [repo\|all]` (`pan sm`)                        | Fetch + merge `origin/main` into current branch (interactive picker; conflict summary)                                                                                                                                                                                                                                         |
+| `pan fetch` (`pan gfa`)                                       | Fetch all remotes — bảng tổng hợp `repo · branch · result · behind/ahead · new refs`                                                                                                                                                                                                                                           |
+| `pan push`                                                    | Push all repos (`-u origin HEAD` by default) — bảng tổng hợp `repo · branch · result · commits · changes · MR/PR link`                                                                                                                                                                                                         |
+| `pan mr [target] [repo\|all\|list]`                           | Create GitLab Merge Requests (interactive multi-select; target defaults to `main`)                                                                                                                                                                                                                                             |
+| `pan checkout [-b\|-B] <branch> [repo\|all\|list]` (`pan co`) | Switch/create branch across repos (interactive multi-select)                                                                                                                                                                                                                                                                   |
+| `pan grv`                                                     | `git remote -v` for workspace + each child repo — bảng tổng hợp `repo · branch · remote · fetch · push` (`push` = `=` khi giống `fetch`; nhiều remote thì gộp `origin (+N)`)                                                                                                                                                   |
+| `pan gst`                                                     | Bảng tổng hợp repos dirty: `repo · branch · state · breakdown · behind/ahead` (repo sạch được ẩn; `--verbose` hoặc `-sb` để in `git status` đầy đủ)                                                                                                                                                                            |
 
 Git options:
 
@@ -169,6 +542,176 @@ Git options:
 - `--dry-run` — print commands only
 - `[manifest]` — manifest path (default: `.project.yaml`)
 
+### `pan clone <url>` — thêm repo mới, tiện như `git clone`
+
+`pan clone` không tham số = clone TẤT CẢ repo trong manifest (như cũ). Truyền
+thêm 1 **git URL** (`https://...`, `git@host:group/repo.git`, hoặc bất kỳ
+chuỗi kết thúc `.git`) thì `pan clone` xử lý khác hẳn:
+
+```bash
+pan clone https://github.com/you/my-repo.git
+# 1. Tách tên dự án từ URL: "my-repo"
+# 2. Ghi thêm vào .project.yaml (KHÔNG phải .project.local.yaml):
+#      - name: my-repo
+#        url: https://github.com/you/my-repo.git
+#        path: apps/my-repo
+# 3. git clone ngay repo đó vào apps/my-repo/
+```
+
+- Giống hệt `git clone <url>` về công dụng, nhưng **tự ghi lại vào manifest** —
+  không cần tay chỉnh `.project.yaml` rồi chạy lại `pan clone`.
+- Đã có repo TÊN ĐÓ trong manifest rồi (kể cả khai ở `.project.local.yaml`) →
+  **không thêm trùng**, dùng lại URL/path đã khai, chỉ clone (idempotent — chạy
+  lại nhiều lần an toàn).
+- `--dry-run` → in ra sẽ ghi gì / clone gì, KHÔNG đụng file `.project.yaml` và
+  không clone thật.
+- `--base-dir DIR` áp dụng như các lệnh git khác (path tương đối tính từ đây).
+- Muốn thêm repo riêng, không muốn commit chung với team? Đừng dùng cách này —
+  tự thêm tay vào `.project.local.yaml` (xem mục riêng phía trên) thay vào đó.
+
+**Không có `.project.yaml`?** Mọi lệnh git ở trên (trừ `pan clone` — cần `url`
+khai báo trong manifest, không tự suy ra được) vẫn chạy: nếu walk-up từ cwd
+không thấy `.project.yaml`, CLI **fallback** coi **chính thư mục đang gõ
+lệnh** là gốc dự án và quét git repo con bên trong (giống cách `pan stats`
+fallback — pwd + tối đa 2 cấp con, bỏ qua `node_modules`/`.git`/`dist`/…). Nhờ
+vậy dùng được `pan pull|push|fetch|checkout|sync-main|mr|grv|gst` ngay cả khi
+chưa có/không dùng workspace pan-stack, miễn thư mục gốc chứa các repo git con.
+
+### Bảng tổng hợp `pull` / `push` / `fetch` / `gst` / `clone` / `grv`
+
+6 lệnh trên chạy git **im lặng** (không xả output raw của từng repo), in một dòng
+tiến trình gọn cho mỗi repo (`  ↻ csdl-cc-backend (main) ... fast-forward`), rồi
+đóng bằng **bảng tổng hợp** ở cuối để bạn nhìn được ngay bức tranh tổng:
+
+- **`pull`** — cột `result` (`up-to-date · fast-forward · merge · rebase · conflict · failed`), `changes` (`N files +add −del`), `conflict` (danh sách file mâu thuẫn ở footer nếu có).
+- **`push`** — cột `result` (`pushed · up-to-date · rejected`), `commits` (số commit `ahead` trước push), `changes` (tổng `N files +add −del` cộng từ mọi commit sắp đẩy), `MR/PR link` (parse URL merge_request/pull do GitLab/GitHub in ở stderr; footer có tổng dòng đã push).
+- **`fetch`** — chạy `git fetch --all --prune`, cột `behind/ahead` so upstream sau fetch (↓ = có commit mới ở remote → gợi ý `pan pull`), `new refs` (new / updated / tags / pruned).
+- **`gst`** — chỉ liệt kê repo dirty / đang merge-rebase / lỗi; hiển thị `state`, `breakdown` (staged/unstaged/untracked), `behind/ahead`; repo sạch được đếm ẩn.
+- **`clone`** — cột `result` (`cloned · already exists · no access · not found · failed`), `note` (dòng lỗi ngắn gọn — chỉ lấy dòng `fatal:`/`remote:`, KHÔNG in nguyên message thô/đường dẫn dài). Clone HẾT các repo rồi mới tổng hợp — 1 repo không có quyền/không tồn tại KHÔNG chặn các repo còn lại.
+- **`grv`** — cột `remote` (tên remote, `origin (+N)` nếu có nhiều remote), `fetch`/`push` (URL; `push` in `=` khi giống hệt `fetch` cho gọn bảng).
+
+Muốn xem output raw thô như trước? Dùng `--verbose` với `gst` (hoặc chạy `git`
+trực tiếp trong repo).
+
+## `pan stats` — Git contribution stats
+
+Thống kê đóng góp Git cho các repo trong `.project.yaml` (đọc `git log`). Vì
+PAN Stack là **vỏ bọc** và không phải ai cũng clone đủ repo, repo nào **thiếu /
+không đọc được** sẽ được **báo lên report** (khung cảnh báo) thay vì làm hỏng
+thống kê. Alias `pan graph`.
+
+**Không có `.project.yaml`?** `pan stats` vẫn chạy: nếu walk-up không thấy
+`.project.yaml`, nó **fallback** quét git từ **chính `pwd` xuống tối đa 2 cấp
+con** (gồm bản thân `pwd`, thư mục con trực tiếp, và 1 cấp con nữa — đủ bắt
+submodule), không đọc sâu hơn. Nhờ vậy dùng được kể cả khi chưa `pan create`/init
+workspace.
+
+| Command              | Action                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `pan stats [report]` | Quét → dựng báo cáo HTML (Tailwind CDN, bảng màu FPT) → serve `localhost:4321` và mở trình duyệt |
+| `pan stats people`   | Liệt kê thành viên tham gia (gộp theo email)                                                     |
+| `pan stats review`   | Xuất Markdown code-change của 1 thành viên × 1 dự án cho AI review/chấm điểm                     |
+
+Bộ lọc thời gian (dùng chung cho mọi lệnh):
+
+- `--since <n>` — preset ngày: `1 2 3 4 5 7 14 30` (30 = "1 tháng")
+- `--from <YYYY-MM-DD> --to <YYYY-MM-DD>` — khoảng ngày tuỳ chọn
+- Không truyền → toàn bộ lịch sử
+
+Options khác:
+
+- `-m, --member <email|tên>` — lọc theo thành viên (bắt buộc với `review`)
+- `-p, --project <tên repo>` — lọc theo dự án (bắt buộc với `review`)
+- `--port <n>` — cổng serve (mặc định `4321`)
+- `--no-open` — không tự mở trình duyệt
+- `-o, --out <file>` — nơi ghi HTML/Markdown
+- `--no-diff` — (`review`) chỉ tóm tắt, bỏ diff
+- `--max-diff-lines <n>` — (`review`) giới hạn số dòng diff (mặc định `6000`)
+- `--head-only` — chỉ quét HEAD hiện tại. **Mặc định** dùng `git log --all` để
+  gộp commit từ **mọi nhánh** (local + remote-tracking + tags), git tự dedupe
+  theo hash. Nếu đồng đội commit ở nhánh chưa có bản sao remote-tracking, chạy
+  `pan fetch` trước để cập nhật.
+
+Báo cáo HTML tương tác (lọc chạy phía client trên toàn bộ commit đã nhúng):
+
+- **Bộ lọc thời gian ngay trên trang**: nút preset `Tất cả · 1n · 2n · 3n · 4n ·
+5n · 7n · 14n · 1 tháng` + ô `from → to` (Áp dụng) cho khoảng ngày tuỳ chọn.
+- **Dropdown chọn thành viên (multi-select)**: checkbox từng người, "Chọn tất
+  cả / Bỏ chọn"; rỗng = tất cả. (Thay cho ô lọc text.)
+- Mỗi thành viên một **card** (1/3 desktop · 50% tablet · full mobile), bấm để
+  bung danh sách dự án với commit + `+add`/`−del`; nút **"Mở tất cả"**.
+- **Bảng tổng hợp** cuối trang có hàng TỔNG — tự cập nhật theo bộ lọc.
+
+Các cờ CLI `--since/--from/--to/--member` chỉ đặt **giá trị khởi tạo** cho báo
+cáo; sau đó lọc trực tiếp trên trình duyệt. (Merge commit bị loại; danh tính gộp
+theo email — sửa tay qua `~/.pan-code-graph/alias-map.json`.)
+
+`pan stats review` xuất file `.md` gồm bảng commit + diff, kèm sẵn **prompt chấm
+điểm 1–10** (đúng đắn · chất lượng · an toàn · test · nhất quán) để dán cho AI.
+
+Đầu ra lưu tại `~/.pan-code-graph/` (`report.html`, `review-*.md`, `alias-map.json`).
+
+Ví dụ:
+
+```bash
+pan stats --since 7                                   # báo cáo 7 ngày gần đây
+pan stats report --from 2026-07-01 --to 2026-07-22    # khoảng ngày tuỳ chọn
+pan stats people --since 30                            # ai tham gia trong 1 tháng
+pan stats review -m an@fpt.com -p csdl-cc-backend --since 7 -o review.md
+```
+
+### `pan mr` — GitLab Merge Requests
+
+Creates Merge Requests for the workspace stack root + each repo in `.project.yaml`
+that has commits ahead of `origin/<target>`. Does NOT auto-push — run `pan push`
+first if HEAD is not on the remote yet. Selection modes:
+
+- `pan mr` — interactive checkbox picker (target = `main`)
+- `pan mr develop` — interactive checkbox picker (target = `develop`)
+- `pan mr main all` — non-interactive, all repos
+- `pan mr main csdl-cc-backend,csdl-cc-b-frontend` — comma/space list
+- `pan mr main csdl-cc-backend` — single repo
+
+Interactive picker theo [quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan) (`menuCheckbox`):
+`↑↓` di chuyển · `space` chọn · `a` chọn tất cả · `i` đảo chọn · `x` thoát · `Enter` xác nhận
+(nếu thiếu `@inquirer/core`, tự fallback `@inquirer/prompts` rồi readline nhập số).
+
+Result rows: `✓` (new MR) · `=` (existing open MR) · `!` (needs `pan push` first) ·
+`-` (skipped: no commits ahead / detached HEAD / already on target) · `✗` (error).
+
+Token resolution: `--token` flag → `GITLAB_TOKEN` env var →
+`<workspace>/.pan-env-build.yaml`. GitLab host is derived per-repo from the
+`origin` remote URL; override with `--gitlab-host HOST` if needed.
+
+### `pan checkout` — switch/create branches across repos
+
+Chuyển hoặc tạo nhánh trên workspace stack root + các repo con trong `.project.yaml`.
+Interactive checkbox picker (arrow keys + space) khi chạy trong TTY và không
+truyền lựa chọn.
+
+- `pan co main` — switch tất cả (tương tác chọn repo)
+- `pan co -b feat/#1234` — tạo nhánh mới từ HEAD (tương tác chọn repo)
+- `pan co -b feat/#1234 all` — tạo trên tất cả repo
+- `pan co -b feat/#1234 csdl-cc-backend,csdl-cc-b-frontend` — tạo trên list cụ thể
+- `pan co -B hotfix/x --start-point origin/main` — force-reset `hotfix/x` từ `origin/main`
+- `pan co develop csdl-cc-backend` — switch một repo
+
+Picker theo [quy ước chung](#quy-ước-chung-cho-mọi-menu-tương-tác-trong-pan): `↑↓` di chuyển ·
+`space` chọn · `a` chọn tất cả · `i` đảo chọn · `x` thoát · `Enter` xác nhận. Non-TTY (stdin bị
+pipe) hoặc CI thì bắt buộc truyền `all` / tên repo / list.
+
+Flags:
+
+- `-b <branch>` — `git checkout -b` (fail nếu nhánh đã tồn tại local)
+- `-B <branch>` — `git checkout -B` (tạo hoặc reset về `--start-point`)
+- `--start-point REF` — base ref cho `-b`/`-B` (default: HEAD hiện tại)
+- `--no-workspace` — bỏ qua workspace stack root
+
+Result rows: `✓` (chuyển/tạo mới) · `=` (đã ở nhánh đó) · `!` (nhánh đã tồn tại
+khi dùng `-b` — dùng `-B` để reset hoặc bỏ `-b` để switch) · `-` (skipped: chưa
+clone / dry-run) · `✗` (lỗi: branch không tồn tại, dirty tree conflict, start-point
+không hợp lệ, v.v.). Không tự stash — commit hoặc `git stash` trước nếu dirty.
+
 Works from child repo directories — the CLI walks up to find `.project.yaml`.
 
 ## Project commands
@@ -179,12 +722,12 @@ use `--project <name>` or pick interactively.
 
 ### Environment variables
 
-| Variable | Meaning |
-|----------|---------|
-| `PAN_WORKSPACE_ROOT` | Directory containing `.project.yaml` |
-| `PAN_REPO_ROOT` | Directory containing the active `.pan.yaml` |
-| `PAN_PROJECT_ROOT` | Alias of `PAN_WORKSPACE_ROOT` |
-| `PAN_ARG_1`, … | Arguments after the command name |
+| Variable             | Meaning                                     |
+| -------------------- | ------------------------------------------- |
+| `PAN_WORKSPACE_ROOT` | Directory containing `.project.yaml`        |
+| `PAN_REPO_ROOT`      | Directory containing the active `.pan.yaml` |
+| `PAN_PROJECT_ROOT`   | Alias of `PAN_WORKSPACE_ROOT`               |
+| `PAN_ARG_1`, …       | Arguments after the command name            |
 
 ### Registry (optional)
 
@@ -202,11 +745,17 @@ pan-stack-cli/
     platform.js             # Windows/cross-platform helpers
     manifest.js             # YAML parsing
     run-command.js        # command execution
-    git/                  # clone, pull, push, fetch, grv, gst
-  templates/workspace/    # pan create template
-  references/             # npm publish docs
+    git/                  # clone, pull, sync-main, push, fetch, mr, checkout, grv, gst
+    stats/                # pan stats: scan git log → report HTML / people / review md
+    skill-registry-client.js  # HTTP client cho registry server (fetch/download/extract — dùng
+                               # chung bởi `pan ai install/update`, `pan create`, `pan ui init`)
+  references/             # npm publish docs (KHÔNG publish lên npm — xem package.json "files")
 ```
 
+Template (`pan create` scaffold + `pan ui init` mẫu landing/mobile/cms) **KHÔNG còn nằm
+trong package này** — sống ở `apps/pan-agent-skill-registry/registry/templates/` và được
+tải qua registry server lúc chạy (xem 2 mục ở trên).
+
 ## Local development
 
 Install globally from source: [references/npm-development.md](references/npm-development.md).