@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/docs/vi/agents/reference/lsp-orchestrator.md

@@ -0,0 +1,60 @@
+<!-- diátaxis: reference -->
+<!-- lang: vi -->
+<!-- draft-translation: needs-human-review -->
+
+> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
+>
+> Đây là bản dịch tiếng Việt do máy tạo ra từ nguồn tiếng Anh tại `../../../agents/reference/lsp-orchestrator.md`.
+> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải do con người dịch trước khi được xem là chính thức. Người rà soát cần kiểm tra, chỉnh sửa thuật ngữ kỹ thuật, và xóa banner này trước khi file trở thành chính thức.
+>
+> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../TRANSLATION-BACKLOG.md)
+
+# LSP Orchestrator
+
+> Thao tác Language Server Protocol phục vụ code intelligence.
+
+## Phạm vi
+
+- **Thực hiện:** Quản lý LSP server, truy vấn symbol, điều hướng tới định nghĩa, và lấy thông tin hover.
+- **Không thực hiện:** Thay thế tính năng của IDE, quản lý vòng đời server ngoài phạm vi VDS, hoặc xử lý các extension LSP.
+- **Đối tượng sử dụng chính:** AI agent (phân tích mã), lập trình viên (điều hướng), đội ngũ công cụ.
+
+## Điểm vào CLI
+
+```bash
+# Qua router thống nhất
+vds-cli lsp --help
+
+# Điểm vào trực tiếp
+vds-cli lsp --help
+```
+
+## Lệnh chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|---------|---------|-------------|
+| `symbol` | Truy vấn symbol trong workspace | `--query` |
+| `navigate` | Điều hướng tới định nghĩa | `--file`, `--line`, `--column` |
+| `hover` | Lấy thông tin hover | `--file`, `--line`, `--column` |
+| `server` | Quản lý LSP server | `--action`, `--language` |
+
+## Quy trình thường gặp
+
+### Quy trình: Tìm định nghĩa của symbol
+
+1. Chạy `vds-cli lsp symbol --query "MyClass"`
+2. Lấy file/dòng/cột từ kết quả
+3. Điều hướng: `vds-cli lsp navigate --file path.py --line 10 --column 5`
+
+## Liên quan
+
+- **Orchestrator:** [intellij](intellij-orchestrator.md), [code-review](code-review-graph-skill.md), [structure](structure-orchestrator.md)
+- **Confluence:** [WHO LSP](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Xử lý sự cố
+
+| Vấn đề | Nguyên nhân | Cách khắc phục |
+|-------|-------|------------|
+| Không tìm thấy lệnh | Orchestrator chưa được cài đặt | Chạy `uv sync --all-packages` |
+| Thiếu cấu hình | Chưa đặt `~/.vds/.env` | Thêm thông tin xác thực cần thiết theo [AGENTS.md](../../../AGENTS.md) |
+| Từ chối quyền truy cập | Không đủ quyền | Kiểm tra phạm vi token Bitbucket/Confluence |

package/skills/vds-skill/runtime/docs/vi/agents/reference/markdown-orchestrator.md

@@ -0,0 +1,62 @@
+<!-- diátaxis: reference -->
+<!-- lang: vi -->
+<!-- draft-translation: needs-human-review -->
+
+> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
+>
+> Đây là bản dịch tiếng Việt do máy tạo ra từ nguồn tiếng Anh tại `../../../agents/reference/markdown-orchestrator.md`.
+> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải do con người dịch trước khi được xem là chính thức. Người rà soát cần kiểm tra, chỉnh sửa thuật ngữ kỹ thuật, và xóa banner này trước khi file trở thành chính thức.
+>
+> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../TRANSLATION-BACKLOG.md)
+
+# Markdown Orchestrator
+
+> Định dạng và kiểm tra markdown cho tài liệu VDS.
+
+## Phạm vi
+
+- **Thực hiện:** Định dạng file markdown với cách ngắt dòng nhất quán, kiểm tra cú pháp markdown, và kiểm tra các file đã staged hoặc được chỉ định về mức độ tuân thủ định dạng.
+- **Không thực hiện:** Render markdown sang HTML hay kiểm tra mục tiêu liên kết (dùng [links-orchestrator](links-orchestrator.md) cho việc đó).
+- **Đối tượng sử dụng chính:** AI agent (vệ sinh tài liệu), lập trình viên (kiểm tra pre-commit).
+
+## Điểm vào CLI
+
+```bash
+# Qua router thống nhất
+vds-cli markdown --help
+
+# Điểm vào trực tiếp
+vds-cli markdown --help
+```
+
+## Lệnh chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|---------|---------|-------------|
+| `check` | Kiểm tra định dạng markdown; thoát với mã khác 0 nếu cần thay đổi | `--staged`, `--wrap` |
+| `format` | Định dạng file markdown tại chỗ | `--staged`, `--wrap` |
+| `version` | Hiển thị phiên bản orchestrator | — |
+
+## Ví dụ quy trình
+
+```bash
+# Kiểm tra mọi file markdown đang được theo dõi
+vds-cli markdown check
+
+# Kiểm tra các file cụ thể
+vds-cli markdown check docs/*.md README.md
+
+# Chỉ kiểm tra các file đã staged
+vds-cli markdown check --staged
+
+# Định dạng với độ rộng ngắt dòng tùy chỉnh
+vds-cli markdown format --wrap 100
+
+# Định dạng các file đã staged
+vds-cli markdown format --staged
+```
+
+## Liên quan
+
+- **Orchestrator:** [links](links-orchestrator.md), [pdf](pdf-orchestrator.md)
+- **Confluence:** [WHO Markdown](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/runtime/docs/vi/agents/reference/mcp-orchestrator.md

@@ -0,0 +1,34 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên MCP
+
+> Bộ định tuyến MCP (Model Context Protocol) và quản lý công cụ.
+
+## Phạm vi
+
+- **Thực hiện:** Định tuyến lệnh gọi công cụ MCP, quản lý đăng ký công cụ, xử lý vòng đời máy chủ MCP.
+- **Không thực hiện:** Thay thế lệnh gọi API trực tiếp, quản lý xác thực nhà cung cấp LLM.
+- **Người dùng chính:** AI agent (phan phối công cụ), nhà phát triển (tích hợp MCP).
+
+## Điểm vào CLI
+
+```bash
+# Qua bộ định tuyến thống nhất
+vds-cli mcp --help
+
+# Điểm vào trực tiếp
+vds-cli mcp-server --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|------|----------|----------------|
+| `list` | Liệt kê công cụ có sẵn | — |
+| `call` | Thực thi lệnh gọi công cụ | `--tool`, `--args` |
+| `health` | Kiểm tra sức khỏe máy chủ MCP | — |
+
+## Liên Quan
+
+- **Điều phối viên:** [research](research-orchestrator.md), [memory](memory-orchestrator.md)
+- **Confluence:** [WHO MCP](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/runtime/docs/vi/agents/reference/memory-orchestrator.md

@@ -0,0 +1,45 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên Bộ Nhớ
+
+> Tìm kiếm, lưu trữ và gợi nhớ kiến thức xuyên phiên cũng như các quan sát.
+
+## Phạm vi
+
+- **Thực hiện:** Tìm kiếm ngữ nghĩa trong kho lưu trữ bộ nhớ, lưu trữ quan sát mới, gợi nhớ quyết định trước đó.
+- **Không thực hiện:** Thay thế lịch sử git, lưu trữ tệp nhị phân lớn.
+- **Người dùng chính:** AI agent (truy xuất ngữ cảnh), người vận hành (khảo cổ quyết định).
+
+## Điểm vào CLI
+
+```bash
+# Qua bộ định tuyến thống nhất
+vds-cli memory --help
+
+# Điểm vào trực tiếp
+vds-cli memory --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|------|----------|----------------|
+| `search` | Tìm kiếm ngữ nghĩa | `--limit`, `--tool` |
+| `store` | Lưu trữ quan sát | `--tag`, `--priority` |
+| `recall` | Gợi nhớ theo ID hoặc thẻ | `--id` |
+| `health` | Kiểm tra sức khỏe kho lưu trữ bộ nhớ | — |
+
+## Quy Trình Thường Gặp
+
+### Quy trình: Nghiên Cứu với Gợi Nhớ Bộ Nhớ
+
+1. Tìm kiếm công việc trước đó: `vds-cli memory search "giao thức MCP" --limit 5`
+2. Xem xét các quan sát đã lưu trữ
+3. Lưu trữ phát hiện mới: `vds-cli memory store --tag "mcp-research-2026"`
+4. Đối chiếu với nhiệm vụ hiện tại
+
+## Liên Quan
+
+- **Điều phối viên:** [research](research-orchestrator.md), [audit](audit-triage-playbook.md)
+- **Skill:** [memory-orchestrator-skill](../../../../vds-skills/skills/memory-orchestrator-skill/SKILL.md)
+- **Confluence:** [WHO Memory](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/runtime/docs/vi/agents/reference/metabase-orchestrator.md

@@ -0,0 +1,30 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên Metabase
+
+> Thao tác analytics và dashboard Metabase.
+
+## Phạm vi
+
+- **Thực hiện:** Truy vấn questions, export kết quả, kiểm tra collections.
+- **Không thực hiện:** Tạo dashboards mới, thay thế Metabase UI.
+- **Người dùng chính:** AI agent (truy xuất dữ liệu), analyst.
+
+## Điểm vào CLI
+
+```bash
+vds-cli metabase --help
+vds-cli metabase --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích |
+|---------|---------|
+| `query` | Chạy Metabase question |
+| `export` | Export kết quả |
+| `collection` | Liệt kê collection |
+
+## Liên Quan
+
+- **Điều phối viên:** [grafana](grafana-orchestrator.md), [db-query](db-query-orchestrator.md)

package/skills/vds-skill/runtime/docs/vi/agents/reference/multi-agent-orchestrator.md

@@ -0,0 +1,61 @@
+<!-- diátaxis: reference -->
+<!-- lang: vi -->
+<!-- draft-translation: needs-human-review -->
+
+> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
+>
+> Đây là bản dịch tiếng Việt do máy tạo từ tài liệu gốc tiếng Anh tại [`../../../agents/reference/multi-agent-orchestrator.md`](../../../agents/reference/multi-agent-orchestrator.md).
+> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải được con người dịch trước khi được coi là tài liệu chính thức. Một biên dịch viên con người phải rà soát, chỉnh sửa thành ngữ và thuật ngữ kỹ thuật, đồng thời gỡ bỏ biểu ngữ này trước khi tệp trở nên có hiệu lực.
+>
+> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../TRANSLATION-BACKLOG.md) (độ sâu đường dẫn có thể khác — điều chỉnh nếu cần)
+
+# Điều phối đa tác tử
+
+> Phối hợp nhiều AI agent cho các tác vụ song song phức tạp.
+
+## Phạm vi
+
+- **Thực hiện:** Điều phối tác vụ tới các đội agent, tổng hợp kết quả, quản lý xung đột và theo dõi tiến độ đội.
+- **Không thực hiện:** Thay thế việc ra quyết định của từng agent, bảo đảm đồng thuận, hoặc quản lý đội con người.
+- **Người dùng chính:** AI agent (phối hợp đội), trưởng nhóm con người (giám sát), người chạy tác vụ phức tạp.
+
+## Điểm vào CLI
+
+```bash
+# Qua bộ định tuyến thống nhất
+vds-cli multi-agent --help
+
+# Điểm vào trực tiếp
+vds-cli multi-agent --help
+```
+
+## Các lệnh chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|---------|---------|-------------|
+| `dispatch` | Điều phối tác vụ tới các agent | `--task`, `--agents`, `--strategy` |
+| `aggregate` | Tổng hợp kết quả từ các agent | `--run-id`, `--method` |
+| `resolve` | Giải quyết xung đột | `--run-id`, `--strategy` |
+| `status` | Kiểm tra trạng thái đội | `--run-id` |
+
+## Quy trình thường gặp
+
+### Quy trình: rà soát mã nguồn song song
+
+1. Điều phối tác vụ rà soát: `vds-cli multi-agent dispatch --task "review PR #123" --agents reviewer-1,reviewer-2,reviewer-3`
+2. Chờ hoàn thành
+3. Tổng hợp kết quả: `vds-cli multi-agent aggregate --run-id <id> --method consensus`
+4. Giải quyết xung đột nếu những người rà soát không đồng thuận
+
+## Liên quan
+
+- **Điều phối viên:** [audit](audit-triage-playbook.md), [evolution](evolution-orchestrator.md), [tasks](tasks-orchestrator.md)
+- **Confluence:** [WHO Multi-Agent](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Xử lý sự cố
+
+| Vấn đề | Nguyên nhân | Hướng xử lý |
+|-------|-------|------------|
+| Không tìm thấy lệnh | Chưa cài điều phối viên | Chạy `uv sync --all-packages` |
+| Thiếu cấu hình | Chưa thiết lập `~/.vds/.env` | Thêm các thông tin đăng nhập cần thiết theo [AGENTS.md](../../../AGENTS.md) |
+| Từ chối quyền | Không đủ quyền hạn | Kiểm tra phạm vi token Bitbucket/Confluence |

package/skills/vds-skill/runtime/docs/vi/agents/reference/openapi-orchestrator.md

@@ -0,0 +1,66 @@
+<!-- diátaxis: reference -->
+<!-- lang: vi -->
+<!-- draft-translation: needs-human-review -->
+
+> ⚠️ **BẢN DỊCH NHÁP — CẦN CON NGƯỜI RÀ SOÁT**
+>
+> Đây là bản dịch tiếng Việt do máy tạo ra từ nguồn tiếng Anh tại `../../../agents/reference/openapi-orchestrator.md`.
+> Theo `.gpt-5.4/specs/who-project-documentation-enhancement/requirements.md`, tài liệu tiếng Việt phải do con người dịch trước khi được xem là chính thức. Người rà soát cần kiểm tra, chỉnh sửa thuật ngữ kỹ thuật, và xóa banner này trước khi file trở thành chính thức.
+>
+> Theo dõi: [`docs/vi/TRANSLATION-BACKLOG.md`](../../TRANSLATION-BACKLOG.md)
+
+# OpenAPI Orchestrator
+
+> Kiểm tra, chuyển đổi schema OpenAPI, và sinh client.
+
+## Phạm vi
+
+- **Thực hiện:** Kiểm tra spec OpenAPI 3.x, chuyển đổi giữa các định dạng (JSON/YAML), sinh stub client, và trích xuất tài liệu endpoint.
+- **Không thực hiện:** Thiết kế API, thay thế Swagger UI, hay quản lý API gateway.
+- **Đối tượng sử dụng chính:** AI agent (rà soát API), lập trình viên (sinh client), QA (kiểm thử hợp đồng).
+
+## Điểm vào CLI
+
+```bash
+# Qua router thống nhất
+vds-cli openapi --help
+
+# Điểm vào trực tiếp
+vds-cli openapi --help
+```
+
+## Lệnh chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|---------|---------|-------------|
+| `validate` | Kiểm tra spec OpenAPI | `--input`, `--strict` |
+| `convert` | Chuyển đổi giữa JSON/YAML | `--input`, `--output` |
+| `generate` | Sinh stub client | `--input`, `--language`, `--output` |
+| `extract` | Trích xuất tài liệu endpoint | `--input`, `--path` |
+
+## Quy trình thường gặp
+
+### Quy trình: Kiểm tra spec API
+
+1. Chạy `vds-cli openapi validate --input api.yaml --strict`
+2. Xem lại các lỗi kiểm tra
+3. Sửa vấn đề và chạy kiểm tra lại
+
+### Quy trình: Sinh client Python
+
+1. Chạy `vds-cli openapi generate --input api.yaml --language python --output client/`
+2. Xem lại mã client được sinh
+3. Thêm vào dependency của dự án
+
+## Liên quan
+
+- **Orchestrator:** [schema](schema-orchestrator.md), [public_interface](public-interface-orchestrator.md)
+- **Confluence:** [WHO OpenAPI](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Xử lý sự cố
+
+| Vấn đề | Nguyên nhân | Cách khắc phục |
+|-------|-------|------------|
+| Không tìm thấy lệnh | Orchestrator chưa được cài đặt | Chạy `uv sync --all-packages` |
+| Thiếu cấu hình | Chưa đặt `~/.vds/.env` | Thêm thông tin xác thực cần thiết theo [AGENTS.md](../../../AGENTS.md) |
+| Từ chối quyền truy cập | Không đủ quyền | Kiểm tra phạm vi token Bitbucket/Confluence |

package/skills/vds-skill/runtime/docs/vi/agents/reference/orchestrator-architecture.md

@@ -0,0 +1,24 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Orchestrator Architecture
+
+The active automation stack is centralized under `WHO-project/vds-scripts`.
+
+## Current Layers
+
+- Workspace root: [WHO project baseline](../../../AGENTS.md)
+- Shared scripts guide: [docs README](../../README.md)
+- Unified router: [vds_cli README](../../../vds_cli/README.md)
+- Audit runtime: [audit_orchestrator README](../../../audit_orchestrator/README.md)
+- Skills catalog: [vds-skills README](../../../../vds-skills/README.md)
+
+## Active Operator Surface
+
+- Spec triplet authority stays under `.gpt-5.4/specs/audit-orchestrator/`.
+- Repo-owned guidance is rooted in `AGENTS.md`, `WHO-project/vds-scripts/audit_orchestrator/README.md`, `WHO-project/vds-skills/skills/audit-orchestrator-skill/SKILL.md`, and the WHO-owned agent docs under `WHO-project/vds-scripts/docs/agents/`.
+- `WHO-project/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/publishers/system_doc_renderer.py` publishes those guidance sources into the system-doc surface, so README and guide drift is user-facing runtime drift, not cosmetic documentation churn.
+- Phase 171 is the active merged mainline baseline for audit control-plane behavior.
+- The current runtime is no longer staged in isolated worktrees for these surfaces; mainline now includes Phase 167 dispatch optimization, Phase 168 finalization reliability, Phase 169 dispatch observability, Phase 170 schema contract hardening, and Phase 171 gradual dispatch ramp-up.
+- The current `workflow-project` lane continues to emit prepared/running/completed summary updates while preserving final aggregate/readiness publication flow; the Phase 171 baseline incorporates gradual ramp-up for `_fill_capacity()` (Phase 171), contract-driven schema validation, safe additive repair of `dispatch_lanes.claimed_at`, startup gating via `dispatch_schema_gate()`, and `doctor schema` operator inspection (Phase 170), plus heartbeat, utilization persistence, progress summaries, and dead-run detection (Phase 169).

package/skills/vds-skill/runtime/docs/vi/agents/reference/orchestrator-index.md

@@ -0,0 +1,73 @@
+<!-- diátaxis: reference -->
+
+# Chỉ Mục Điều Phối Viên
+
+> Tham khảo nhanh cho tất cả 28 điều phối viên VDS.
+
+## Nền Tảng Cốt Lõi
+
+| Điều phối viên | Mục đích | Điểm vào CLI | Tài liệu |
+|---------------|----------|--------------|----------|
+| audit | Thực thi và báo cáo audit | `vds-cli audit` | [audit-triage-playbook](audit-triage-playbook.md) |
+| bitbucket | Thao tác Bitbucket | `vds-cli bitbucket-cli` | [cli-commands](cli-commands.md) |
+| brd | Tài liệu yêu cầu nghiệp vụ | `vds-cli brd` | [brd-orchestrator](brd-orchestrator.md) |
+| circular-dependency | Phát hiện phụ thuộc vòng | `vds-cli circular-dependency` | [circular-dependency-orchestrator](circular-dependency-orchestrator.md) |
+| confluence | Thao tác Confluence | `vds-cli confluence-cli` | [cli-commands](cli-commands.md) |
+| db-query | Thao tác truy vấn cơ sở dữ liệu | `vds-cli db-query` | [db-query-orchestrator](db-query-orchestrator.md) |
+| diagrams | Tạo sơ đồ | `vds-cli diagrams` | [diagrams-orchestrator](diagrams-orchestrator.md) |
+| elastic | Thao tác Elasticsearch | `vds-cli elastic` | [elastic-orchestrator](elastic-orchestrator.md) |
+| evolution | Vòng lặp tiến hóa hệ sinh thái | `vds-cli evolution` | [evolution-orchestrator](evolution-orchestrator.md) |
+| excel | Xử lý Excel | `vds-cli excel` | [excel-orchestrator](excel-orchestrator.md) |
+| git | Thao tác kho lưu trữ git | `vds-cli git-orchestrator` | [cli-commands](cli-commands.md) |
+| google-sheets | Tích hợp Google Sheets | `vds-cli google-sheets` | [google-sheets-orchestrator](google-sheets-orchestrator.md) |
+| grafana | Log và chỉ số Grafana | `vds-cli grafana` | [grafana-orchestrator](grafana-orchestrator.md) |
+| hexagonal | Tuân thủ hexagonal | `vds-cli hexagonal` | [hexagonal-orchestrator](hexagonal-orchestrator.md) |
+| intellij | Thao tác plugin IntelliJ | `vds-cli intellij` | [intellij-orchestrator](intellij-orchestrator.md) |
+| jira | Thao tác JIRA | `vds-cli jira-cli` | [cli-commands](cli-commands.md) |
+| links | Xác thực liên kết | `vds-cli links` | [links-orchestrator](links-orchestrator.md) |
+| lsp | Giao thức máy chủ ngôn ngữ | `vds-cli lsp` | [lsp-orchestrator](lsp-orchestrator.md) |
+| markdown | Xử lý Markdown | `vds-cli markdown` | [markdown-orchestrator](markdown-orchestrator.md) |
+| mcp | Bộ định tuyến và công cụ MCP | `vds-cli mcp-server` | [mcp-orchestrator](mcp-orchestrator.md) |
+| memory | Tìm kiếm và lưu trữ bộ nhớ | `vds-cli memory` | [memory-orchestrator](memory-orchestrator.md) |
+| metabase | Phân tích Metabase | `vds-cli metabase` | [metabase-orchestrator](metabase-orchestrator.md) |
+| multi-agent | Điều phối đa agent | `vds-cli multi-agent` | [multi-agent-orchestrator](multi-agent-orchestrator.md) |
+| openapi | Thao tác schema OpenAPI | `vds-cli openapi` | [openapi-orchestrator](openapi-orchestrator.md) |
+| pdf | Tạo PDF | `vds-cli pdf` | [pdf-orchestrator](pdf-orchestrator.md) |
+| progress | Báo cáo tiến độ | `vds-cli progress` | [progress-orchestrator](progress-orchestrator.md) |
+| public-interface | Phân tích API công khai | `vds-cli public-interface` | [public-interface-orchestrator](public-interface-orchestrator.md) |
+| research | Nghiên cứu và bằng chứng | `vds-cli research` | [research-orchestrator](research-orchestrator.md) |
+| schema | Chuyển đổi schema | `vds-cli schema-convert` | [schema-orchestrator](schema-orchestrator.md) |
+| sonarqube | Tích hợp SonarQube | `vds-cli sonarqube` | [sonarqube-orchestrator](sonarqube-orchestrator.md) |
+| spec | Tạo đặc tả | `vds-cli spec` | [spec-orchestrator](spec-orchestrator.md) |
+| structure | Phân tích cấu trúc mã | `vds-cli structure` | [structure-orchestrator](structure-orchestrator.md) |
+| tasks | Quản lý tác vụ | `vds-cli tasks` | [tasks-orchestrator](tasks-orchestrator.md) |
+
+## Theo Danh Mục
+
+### Audit & Báo Cáo
+- [audit](audit-triage-playbook.md), [progress](progress-orchestrator.md), [spec](spec-orchestrator.md)
+
+### Dữ Liệu & Phân Tích
+- [db-query](db-query-orchestrator.md), [elastic](elastic-orchestrator.md), [grafana](grafana-orchestrator.md), [metabase](metabase-orchestrator.md), [google-sheets](google-sheets-orchestrator.md), [excel](excel-orchestrator.md)
+
+### Chất Lượng Mã
+- [circular-dependency](circular-dependency-orchestrator.md), [hexagonal](hexagonal-orchestrator.md), [sonarqube](sonarqube-orchestrator.md), [structure](structure-orchestrator.md), [public-interface](public-interface-orchestrator.md), [intellij](intellij-orchestrator.md), [lsp](lsp-orchestrator.md)
+
+### Tài Liệu
+- [confluence](cli-commands.md), [markdown](markdown-orchestrator.md), [pdf](pdf-orchestrator.md), [diagrams](diagrams-orchestrator.md), [brd](brd-orchestrator.md)
+
+### Nghiên Cứu & Trí Tuệ
+- [research](research-orchestrator.md), [memory](memory-orchestrator.md), [mcp](mcp-orchestrator.md)
+
+### DevOps
+- [git](cli-commands.md), [bitbucket](cli-commands.md), [jira](cli-commands.md), [links](links-orchestrator.md), [openapi](openapi-orchestrator.md), [schema](schema-orchestrator.md)
+
+### Điều Phối
+- [tasks](tasks-orchestrator.md), [multi-agent](multi-agent-orchestrator.md), [evolution](evolution-orchestrator.md)
+
+## Liên Quan
+
+- [Kiến Trúc Điều Phối Viên](orchestrator-architecture.md)
+- [Tham Khảo Lệnh CLI](cli-commands.md)
+- [Ma Trận Trợ Giúp CLI](cli-help-matrix.md)
+- [Tham Khảo Skill](skills-reference.md)

package/skills/vds-skill/runtime/docs/vi/agents/reference/pdf-orchestrator.md

@@ -0,0 +1,30 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên PDF
+
+> Tạo PDF từ markdown và các định dạng khác.
+
+## Phạm vi
+
+- **Thực hiện:** Chuyển đổi markdown sang PDF, áp dụng templates, batch generate.
+- **Không thực hiện:** Chỉnh sửa PDF hiện có, OCR.
+- **Người dùng chính:** AI agent (giao tài liệu), operator.
+
+## Điểm vào CLI
+
+```bash
+vds-cli pdf --help
+vds-cli pdf --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích |
+|---------|---------|
+| `vds-cli pdf md2pdf` | Markdown sang PDF |
+| `template` | Áp dụng template |
+| `batch` | Batch generate |
+
+## Liên Quan
+
+- **Điều phối viên:** [markdown](markdown-orchestrator.md), [diagrams](diagrams-orchestrator.md)

package/skills/vds-skill/runtime/docs/vi/agents/reference/portable-paths-and-config.md

@@ -0,0 +1,123 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Portable path and configuration model
+
+This reference defines the WHO `vds-scripts` Phase 2 path and configuration contract.
+Use it when you need to understand where VDS stores configuration, cache, logs,
+and shared `.env` data across macOS, Ubuntu/Linux, and Windows-oriented setups.
+
+## Goals
+
+- Remove machine-specific assumptions from maintained runtime guidance.
+- Keep overrides explicit and predictable.
+- Use a friendly portable-path contract for maintained runtime surfaces.
+- Separate user-editable config from cache/data/log outputs.
+
+## Canonical path taxonomy
+
+| Surface | Meaning | Examples |
+| --- | --- | --- |
+| Workspace-relative | Paths inside the checked-out WHO workspace | `WHO-project/vds-scripts/`, `WHO-project/vds-skills/skills/` |
+| User-config | User-editable shared configuration root | `VDS_CONFIG_DIR`, `~/.vds` |
+| Shared env file | Shared secrets/credentials env file loaded by CLI bootstrap | `VDS_ENV_FILE`, `<config-root>/.env` |
+| Cache/data/log | Derived runtime outputs and safe-to-regenerate state | `VDS_CACHE_DIR`, `VDS_DATA_DIR`, `VDS_LOG_DIR` |
+| Machine-specific | Host-local absolute paths for ad hoc debugging only | `/Users/alice/...`, `C:\Users\Alice\...` |
+
+## Directory resolution model
+
+The shared helper layer lives in `vds_cli_common.paths` and uses one canonical user-home VDS root as the active default.
+
+### Effective default roots
+
+Resolution starts with explicit env overrides. If no override is provided, the runtime
+uses the friendly user-home VDS defaults.
+
+1. **Config root**
+   - `VDS_CONFIG_DIR`
+   - `~/.vds` on Unix-like systems
+2. **Cache root**
+   - `VDS_CACHE_DIR`
+   - `<config-root>/cache`
+3. **Data root**
+   - `VDS_DATA_DIR`
+   - `<config-root>/data`
+4. **Log root**
+   - `VDS_LOG_DIR`
+   - `<config-root>/logs`
+
+## Shared environment precedence
+
+All CLI bootstrap flows load shared environment variables through `vds_cli_common.env`.
+The precedence model is:
+
+1. Runtime arguments for a command or orchestrator
+2. Existing shell environment variables
+3. Values from the shared env file (`VDS_ENV_FILE` or `<config-root>/.env`)
+4. Derived defaults from code/config models
+
+Important behavior:
+
+- Existing shell values win by default and are not overwritten by `.env` loading.
+- `load_shared_env(..., override=True)` is the explicit opt-in for replacing existing shell values.
+- `ensure_shared_env()` creates the shared env file with safe defaults only and never overwrites existing values.
+
+## Maintained Phase 2 contract
+
+Maintained runtime surfaces in Phase 2 use a friendly portable-path contract.
+
+- Explicit VDS overrides win.
+- Otherwise, config/cache/data/log roots resolve from the canonical user-home VDS root.
+- Maintained docs and examples should advertise only the active override-plus-user-home-VDS contract.
+
+## Recommended operator patterns
+
+### Monorepo or canonical WHO checkout
+
+- Keep workspace-relative paths inside the repository.
+- Keep secrets in the shared env file at `VDS_ENV_FILE` or `<config-root>/.env`.
+- Use env overrides when you need non-default config/cache/log locations.
+
+### External clone or CI environment
+
+- Set `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, and `VDS_ENV_FILE` explicitly when reproducibility matters.
+- Avoid baking host-specific absolute paths into checked-in scripts or docs.
+- Keep the shared env file explicit; do not rely on repo-local `.env` fallback in maintained automation.
+
+## Platform notes
+
+### macOS
+
+- Use `VDS_*` overrides when you need explicit locations.
+- Otherwise rely on the active user-home VDS root defaults for maintained automation.
+
+### Ubuntu/Linux
+
+- Prefer explicit overrides or the active `~/.vds` defaults instead of hardcoding host-specific config roots in new automation.
+- Keep shell examples POSIX-friendly, but document override variables rather than host-specific account paths.
+
+### Windows-oriented environments
+
+- Use `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, `VDS_DATA_DIR`, `VDS_LOG_DIR`, and `VDS_ENV_FILE` instead of hardcoded POSIX paths.
+- Prefer environment-variable-driven examples over path separators embedded in commands.
+- Treat Windows path separators as an operator concern solved by the override variables, not by checked-in absolute examples.
+
+## Safe-to-edit vs safe-to-delete surfaces
+
+| Surface | Editable | Safe to delete |
+| --- | --- | --- |
+| Shared env file | Yes | No |
+| User config files | Yes | No |
+| Cache/data/log outputs | Usually no | Yes, if you intend to regenerate them |
+| Repo-local fallback `.env` | Only for local safe defaults | Yes, if not used locally |
+
+## Practical checks
+
+- Show current env/bootstrap status: `./scripts/worktree_uv.sh run --project vds_cli vds-cli env status`
+- Confirm CLI health: `./scripts/worktree_uv.sh run --project vds_cli vds-cli status`
+- Diagnose config/auth issues: `./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor`
+- Review the verification lanes and evidence posture in `portable-paths-validation-matrix.md`
+- Run Docker-based Ubuntu verification when Docker is available: `./scripts/verification/phase2_portable_paths_ubuntu_docker.sh`
+
+Use this reference together with `cli-commands.md`, `vds-cli-reference.md`, and `portable-paths-validation-matrix.md` when updating docs, examples, bootstrap logic, or portability evidence.