@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/portable-paths-validation-matrix.md

@@ -0,0 +1,131 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Portable path/config validation matrix
+
+This reference turns the Phase 2 portability spec into an executable validation posture.
+It records what should be validated natively on the host, what can be validated in
+Docker-based Ubuntu/Linux, and what must remain Windows-oriented simulation unless a
+real Windows environment is available.
+
+## Verification lanes
+
+| Lane | Purpose | Environment | Evidence type |
+| --- | --- | --- | --- |
+| macOS native | Confirm the host development environment uses the shared helper and respects overrides | Current macOS host | Focused tests + manual CLI smoke |
+| Ubuntu/Linux via Docker | Confirm the helper and focused tests behave in real Linux userspace | Docker container on current host | Scripted test run |
+| Windows-oriented simulation | Confirm Windows path/env semantics are modeled correctly in code/docs/tests | Non-Windows host | Contract tests + documented examples |
+| Windows native (future) | Confirm behavior on real Windows filesystem/shell/env | Real Windows host or CI runner | Deferred unless available |
+
+## Current Phase 2 evidence contract
+
+When reporting portability status, classify each result as one of:
+
+- `native-macos`
+- `docker-ubuntu`
+- `windows-simulated`
+- `windows-native`
+- `deferred`
+
+Do not collapse these into one generic “cross-platform verified” claim.
+
+## Recommended checks by lane
+
+### 1. macOS native
+
+Run on the active development host.
+
+Recommended checks:
+- `uv run --project vds_cli_common pytest vds_cli_common/tests/test_paths.py vds_cli_common/tests/test_env.py`
+- `PYTHONPATH=audit_orchestrator/src:vds_cli_common/src:bitbucket_orchestrator/src:confluence_orchestrator/src:sonarqube_orchestrator/src:google_sheets_orchestrator/src:excel_orchestrator/src:git_orchestrator/src:vds_cli/src:spec_orchestrator/src ./scripts/worktree_uv.sh run --project audit_orchestrator pytest audit_orchestrator/tests/test_paths_config_phase2.py audit_orchestrator/tests/test_cli_paths_phase2.py audit_orchestrator/tests/unit/scripts/test_verify_phase124_handoff.py`
+- optional smoke: `./scripts/worktree_uv.sh run --project vds_cli vds-cli env status`
+
+Expected evidence:
+- shared helper tests pass
+- audit orchestrator focused path/log/report tests pass
+- no host-specific absolute paths are required for the focused path/config workflow
+
+### 2. Ubuntu/Linux via Docker
+
+Use a Linux container because it exercises real Linux path behavior while reusing the mounted worktree.
+
+Recommended command:
+- `./scripts/verification/phase2_portable_paths_ubuntu_docker.sh`
+- underlying compose asset: `docker/compose.phase2-verification.yml`
+
+Expected evidence:
+- Linux container test run passes through the supported script entrypoint
+- explicit `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, `VDS_LOG_DIR`, and `VDS_ENV_FILE` overrides work
+- the container uses its own verification environment path rather than depending on the mounted host `.venv`
+- the Docker lane uses an explicit container-local uv cache and verbose/frozen setup for reproducible troubleshooting
+- no hidden dependency on macOS-only paths remains in the focused verification set
+
+Limits:
+- this is Linux verification, not Windows verification
+- Docker Desktop mount behavior is still host-mediated and should not be confused with a fully independent machine
+
+### 3. Windows-oriented simulation / contract validation
+
+Use this lane on macOS/Linux hosts when no real Windows runner is available.
+
+Recommended evidence:
+- focused unit tests around helper precedence and path handling
+- documented Windows override examples in `portable-paths-and-config.md`
+- command/reference surfaces that avoid hardcoded POSIX-only assumptions
+- placeholder-based repo-cache/report-root examples instead of claiming native Windows execution
+
+Expected evidence:
+- Windows-specific separators and override semantics are accounted for in docs and helper contract
+- path/env model does not assume POSIX shell expansion as the only setup path
+
+Limits:
+- this is not proof of native PowerShell/CMD behavior
+- this is not proof of native Windows filesystem edge cases
+
+### 4. Windows native (future lane)
+
+Use only when a real Windows host or CI runner is available.
+
+Recommended future checks:
+- run the focused Phase 2 pytest suite on Windows
+- verify `VDS_CONFIG_DIR`, `VDS_CACHE_DIR`, `VDS_LOG_DIR`, `VDS_ENV_FILE` from PowerShell
+- verify path rendering and shell examples against real Windows defaults
+
+Status for current host-driven Phase 2 work:
+- `deferred`
+
+## Validation matrix
+
+| Check | macOS native | Docker Ubuntu | Windows simulated | Windows native |
+| --- | --- | --- | --- | --- |
+| Shared helper precedence tests | Yes | Yes | Yes | Deferred |
+| Audit report/log default tests | Yes | Yes | Yes | Deferred |
+| CLI/bootstrap smoke | Yes | Optional | Docs/examples only | Deferred |
+| Native filesystem semantics | Yes | Yes | No | Deferred |
+| Native shell semantics | Yes | Yes (bash) | No | Deferred |
+| PowerShell/CMD semantics | No | No | Partial docs/contracts | Deferred |
+
+## Reporting template
+
+Use this structure when recording Phase 2 evidence:
+
+- `native-macos`: what commands/tests ran, pass/fail, notes
+- `docker-ubuntu`: image used, commands/tests ran, pass/fail, notes
+- `windows-simulated`: tests/docs/contracts exercised, pass/fail, notes
+- `windows-native`: `deferred` unless a real environment was used
+
+Current implementation evidence:
+- `docs/phases/phase2-portable-paths/verification-evidence-2026-03-23.md`
+
+## Decision rule for Phase 2 closure
+
+Phase 2 can claim:
+- native macOS validation
+- Docker-based Ubuntu/Linux validation
+- Windows-oriented simulation/contract validation
+
+Phase 2 should **not** claim:
+- native Windows verification
+
+unless an actual Windows host/CI lane produced evidence.

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/progress-orchestrator.md

@@ -0,0 +1,43 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên Tiến Độ
+
+> Báo cáo và trực quan hóa tiến độ xuyên các giai đoạn và làn audit VDS.
+
+## Phạm vi
+
+- **Thực hiện:** Tạo báo cáo tiến độ, theo dõi chỉ số hoàn thành, trực quan hóa trạng thái giai đoạn.
+- **Không thực hiện:** Thực thi audit, sửa đổi trạng thái tác vụ trực tiếp.
+- **Người dùng chính:** Người phụ trách (xem xét trạng thái), AI agent (tự báo cáo).
+
+## Điểm vào CLI
+
+```bash
+# Qua bộ định tuyến thống nhất
+vds-cli progress --help
+
+# Điểm vào trực tiếp
+vds-cli progress --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|------|----------|----------------|
+| `report` | Tạo báo cáo tiến độ | `--phase`, `--lane` |
+| `summary` | Tóm tắt trạng thái một dòng | `--format` |
+| `visualize` | Dòng thời gian ASCII hoặc HTML | `--output` |
+
+## Quy Trình Thường Gặp
+
+### Quy trình: Kiểm Tra Tiến Độ Giai Đoạn
+
+1. Chạy `vds-cli progress report --phase 174`
+2. Xem xét tỷ lệ phần trăm hoàn thành theo wave
+3. Xác định tác vụ bị chặn
+4. Xuất cho standup: `vds-cli progress summary --format markdown`
+
+## Liên Quan
+
+- **Điều phối viên:** [tasks](tasks-orchestrator.md), [audit](audit-triage-playbook.md), [spec](spec-orchestrator.md)
+- **Confluence:** [WHO Progress](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/progress-report-cli.md

@@ -0,0 +1,217 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Progress Report CLI Reference
+
+## Overview
+
+The `vds-cli progress` CLI generates multi-dimensional alignment progress reports for
+INSURANCE-AI projects. It parses a BMAD knowledge graph, runs structural analysis
+across repos, and optionally scores with LLMs.
+
+Entry point: `vds-cli progress` (direct) or `vds-cli progress` (router)
+
+## Commands
+
+### `vds-cli progress report`
+
+Generate a progress report.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p` / `--bitbucket-project` | TEXT | *required* | Bitbucket project key |
+| `--bmad-repo` | TEXT | `bmad_ntbh` | Knowledge graph repo |
+| `--output-dir` | PATH | `~/.vds/cache/progress-reports` | Report output directory |
+| `--max-concurrent` | INT | `4` | Max parallel structural + LLM analyses |
+| `--profile` | TEXT | None | LLM runtime profile |
+| `--llm-provider` | TEXT | `auto` | `auto`, `openai`, `anthropic`, `ollama`, `none` |
+| `--dimensions` | TEXT | `all` | `all` or `structural` |
+| `--fr` | TEXT | None | Single FR deep-dive (e.g. `FR8`) |
+| `--format` | TEXT | `markdown` | `markdown` or `json` |
+| `--skip-sync` | FLAG | False | Skip repo sync |
+| `--resume-run-id` | TEXT | None | Resume interrupted run |
+| `--mode` | TEXT | `standard` | Rendering tier: `exec` (≤20 lines), `summary` (≤100), `standard` (Phase 3 backward-compat), `full` (everything) |
+| `--fail-under` | FLOAT | None | Exit 2 if overall_score below threshold (CI gate) |
+| `--fail-on-regression` | FLAG | False | Exit 2 if any FR has critical regression (Δ ≤ -15) |
+| `--baseline` | TEXT | None | Explicit baseline run_id for regression comparison (overrides "previous run" default) |
+| `-v` / `--verbose` | FLAG | False | DEBUG-level logging |
+| `-q` / `--quiet` | FLAG | False | Suppress all log output |
+
+### `vds-cli progress topology`
+
+Dump the parsed knowledge graph as JSON.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p` / `--bitbucket-project` | TEXT | *required* | Bitbucket project key |
+| `--bmad-repo` | TEXT | `bmad_ntbh` | Knowledge graph repo |
+| `-q` / `--quiet` | FLAG | False | Suppress log output |
+
+### `vds-cli progress db init`
+
+Create all 5 tables (idempotent).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--dsn` | TEXT | env | Postgres DSN |
+
+### `vds-cli progress db status`
+
+Show table presence, run count, and last score.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--dsn` | TEXT | env | Postgres DSN |
+
+## LLM Provider Semantics (`--llm-provider`)
+
+| Value | Behavior |
+|-------|----------|
+| `auto` (default) | Detect cloud LLM from env vars (`OPENAI_API_KEY`, `ANTHROPIC_AUTH_TOKEN`). If none found, degrade gracefully: dims 7-8 stay `None`, score renormalizes across structural dims. Produces the **same score as `none`** when no credentials are available. |
+| `openai` | Force OpenAI — requires `OPENAI_API_KEY` or `VDS_AUDIT_LLM__API_KEY`. |
+| `anthropic` | Force Anthropic — requires `ANTHROPIC_AUTH_TOKEN` or `VDS_AUDIT_LLM__API_KEY`. |
+| `ollama` | Force Ollama at `localhost:11434`. **Not** part of auto-detect — must be explicit. |
+| `none` | Hard-disable LLM scoring. Dims 7-8 stay `None`, structural-only renormalization applies. |
+
+**Why Ollama is opt-in only:** Local Ollama installations may have cloud-routed models (need auth), embedding-only models (no chat support), or reasoning models that need larger `max_tokens`. Aggressive auto-detection caused score regressions. Users who want Ollama scoring must pass `--llm-provider ollama` explicitly.
+
+## Rendering Modes (`--mode`, Phase 4)
+
+Four-tier progressive disclosure. Every mode uses the same underlying
+computation — modes are purely rendering flags.
+
+| Mode | Line budget | Content | Use case |
+|------|------------|---------|----------|
+| `exec` | ≤ 20 | Title, overall score, delta, one-line distribution, top-1 action | Slack/email notifications, GitHub status checks |
+| `summary` | ≤ 100 | Exec content + full summary table + top-3 + score distribution + bimodal callout + dimension coverage | Standup view, code review context |
+| `standard` (default) | ≈ 564 | Phase 3 backward-compat output (heatmap, repo health, per-FR detail, trend, risk register). **Byte-identical to Phase 3** — guarded by G-Q11c snapshot gate | Daily development review |
+| `full` | ≈ 581 | Standard + stratified cluster sub-reports + appendices | Audit / compliance / retrospective |
+
+**Backward compatibility guarantee**: `--mode standard` produces the same
+markdown output as pre-Phase-4 default mode. Phase 4 features (bimodal
+callout, stratified sub-reports, dual-metric coverage with sparklines,
+regression subsections) appear only in `summary` and `full` modes.
+
+## CI/CD Exit Codes (Phase 4)
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | Report generated, no gates tripped |
+| `1` | Runtime error (DSN missing, sync failed, crash) |
+| `2` | **Quality gate failed** — report file still written |
+
+Gate flags:
+
+| Flag | Effect |
+|------|--------|
+| `--fail-under <score>` | Exit 2 if `overall_score < score` |
+| `--fail-on-regression` | Exit 2 if any FR has `Δ ≤ -15` vs baseline |
+| `--baseline <run-id>` | Explicit baseline comparison (overrides "previous run" default) |
+
+**⚠ SonarQube anti-pattern avoided**: The SonarQube `sonar-scanner` CLI
+returns exit code 0 by default even when quality gates fail, unless you
+explicitly pass `-Dsonar.qualitygate.wait=true`. This has silently broken
+countless CI pipelines. `vds-cli progress report` does NOT have this trap —
+`--fail-under` and `--fail-on-regression` are opt-in, but when set they
+ARE honored immediately. Report file is ALWAYS written before exit 2, so
+CI artifacts are always captured.
+
+**Example CI usage**:
+```bash
+vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
+# exits 2 when score < 60; report still written to ~/.vds/cache/progress-reports/
+echo $?  # 2
+```
+
+## Bimodal Detection / Valence-Gap Heuristic (ADR-Q7, Phase 4)
+
+When the score distribution has a valence gap (no medium tier), the report
+emits a `bimodal_warning` block in both markdown and JSON, with stratified
+`high_cluster` / `low_cluster` sub-reports.
+
+Detection rules (all 4 must hold):
+1. `total_frs >= 10` (minimum N)
+2. `medium == 0`
+3. `high > 0 AND low > 0`
+4. `min(high, low) / total >= 0.25` (dominance guard)
+
+**Terminology**: the implementation uses `_detect_valence_gap` internally
+per ADR-Q7 — this is a UX heuristic, NOT statistical bimodality. True
+bimodal detection requires Hartigan's dip test with N ≥ 30. The JSON API
+field name `bimodal_warning` is retained for API stability.
+
+**`bimodal_warning` JSON schema** (when `detected: true`):
+
+```json
+{
+  "detected": true,
+  "high_count": 7,
+  "low_count": 8,
+  "interpretation": "Score splits into high-performers (7 FRs ≥ 60) and low-performers (8 FRs < 30) with no medium tier.",
+  "stratification_variable": "service_exists",
+  "high_cluster": {
+    "label": "passing",
+    "fr_ids": ["FR6", "FR7", "FR8"],
+    "avg_score": 83.6,
+    "dominant_blocker": "test_coverage",
+    "top_recommendation_fr": "FR8"
+  },
+  "low_cluster": {
+    "label": "blocked",
+    "fr_ids": ["FR1", "FR2"],
+    "avg_score": 12.4,
+    "dominant_blocker": "service_exists",
+    "top_recommendation_fr": "FR1"
+  }
+}
+```
+
+When `detected: false`, only `{"detected": false}` is returned.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VDS_PROGRESS_STATE_DSN` | PostgreSQL DSN for run persistence. Set in `~/.vds/.env`. |
+| `VDS_AUDIT_LLM_ENABLED` | Set to `0`/`false`/`no` to hard-disable LLM in auto mode. |
+| `OPENAI_API_KEY` | Auto-detected by auto mode → uses `openai` provider. |
+| `ANTHROPIC_AUTH_TOKEN` | Auto-detected by auto mode → uses `anthropic` provider. |
+| `VDS_AUDIT_LLM__BASE_URL` | Override LLM base URL (for explicit providers). |
+| `VDS_AUDIT_LLM__MODEL_STANDARD` | Override LLM model name. |
+
+## Database Schema
+
+5 tables managed by `db init`:
+
+| Table | Purpose |
+|-------|---------|
+| `progress_runs` | Run metadata, checkpoint phase, overall score |
+| `fr_assessments` | Per-FR dimension scores (structural + LLM) |
+| `document_hashes` | SHA-256 hashes for incremental analysis |
+| `service_analyses` | Per-repo structural metrics (LOC, tests, endpoints) |
+| `daily_scores` | One row per project per day for trend tracking |
+
+## Output Files
+
+Reports are written to `~/.vds/cache/progress-reports/<PROJECT>/`:
+
+- `<date>.json` — Machine-readable JSON with all FR scores
+- `<date>.md` — Markdown with executive summary, risk table, per-FR breakdown
+
+## Examples
+
+```bash
+# Quick structural check
+vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
+
+# Pipe JSON to jq
+vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
+  | jq '.overall_score'
+
+# Topology exploration
+vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
+
+# Check last score
+vds-cli progress db status
+```

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/public-interface-orchestrator.md

@@ -0,0 +1,82 @@
+<!-- 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/public-interface-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)
+
+# Public interface orchestrator
+
+> Trích xuất bằng chứng về ranh giới public interface phục vụ audit tuân thủ.
+
+## Phạm vi
+
+- **Làm:** Quét các repo để phát hiện import có khả năng vi phạm ranh giới (internal, impl, adapter, infrastructure), tạo bằng chứng heuristic cho các mục checklist audit.
+- **Không làm:** Khẳng định chắc chắn việc vi phạm — kết quả cần được xác nhận thủ công kèm phân tích cú pháp.
+- **Người dùng chính:** AI agent (thu thập bằng chứng audit), đội ngũ rà soát tuân thủ.
+
+## Điểm vào CLI
+
+```bash
+# Qua router thống nhất
+vds-cli public-interface --help
+
+# Direct entry
+vds-cli public-interface --help
+```
+
+## Lệnh chính
+
+| Lệnh | Mục đích | Flag thường dùng |
+|------|----------|------------------|
+| `scan-repo` | Quét một repo cho các import ứng viên vi phạm ranh giới | `--json/--no-json`, `--output` |
+| `scan-project` | Quét thư mục project chứa nhiều repo | `--json/--no-json`, `--output` |
+
+## Heuristic phát hiện
+
+Quét các file `.py`, `.java`, `.kt`, `.ts`, `.tsx`, `.js`, `.jsx` (trừ test) để tìm:
+
+- Import `internal`
+- Import `impl` / `adapter`
+- Import `infrastructure`
+- Import các ký hiệu `*Impl` / `*Implementation`
+
+## Ví dụ quy trình
+
+```bash
+# Quét một repo
+vds-cli public-interface scan-repo /path/to/repo
+
+# Quét và lưu JSON
+vds-cli public-interface scan-repo /path/to/repo --output boundary-evidence.json
+
+# Quét thư mục project chứa nhiều repo
+vds-cli public-interface scan-project /path/to/project --output project-boundary.json
+
+# Output dạng người đọc (không JSON)
+vds-cli public-interface scan-repo /path/to/repo --no-json
+```
+
+## Định dạng output
+
+```json
+{
+  "command": "scan-repo",
+  "scope": "repo",
+  "shared_companion_only": true,
+  "files_scanned": 150,
+  "candidate_file_count": 3,
+  "result_type": "evidence_gap",
+  "reasoning": "...",
+  "candidates": [...]
+}
+```
+
+## Liên quan
+
+- **Orchestrators:** [hexagonal](hexagonal-orchestrator.md), [structure](structure-orchestrator.md)
+- **Confluence:** [WHO Public Interface](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/research-orchestrator.md

@@ -0,0 +1,45 @@
+<!-- diátaxis: reference -->
+
+# Điều Phối Viên Nghiên Cứu
+
+> Nghiên cứu kỹ thuật ưu tiên bằng chứng, kết hợp bằng chứng kho lưu trữ cục bộ với các nguồn bên ngoài.
+
+## Phạm vi
+
+- **Thực hiện:** Tìm kiếm mã nguồn cục bộ (rg, sg, grepai), truy vấn API bên ngoài (Tavily, Exa, Context7), chấm điểm bằng chứng, tạo gói nghiên cứu.
+- **Không thực hiện:** Đưa ra quyết định thay bạn, thay thế phán đoán của con người về các lựa chọn chiến lược.
+- **Người dùng chính:** AI agent (xác thực sự thật), người phụ trách (đánh giá công nghệ).
+
+## Điểm vào CLI
+
+```bash
+# Qua bộ định tuyến thống nhất
+vds-cli research --help
+
+# Điểm vào trực tiếp
+vds-cli research --help
+```
+
+## Các Lệnh Chính
+
+| Lệnh | Mục đích | Cờ thường dùng |
+|------|----------|----------------|
+| `search` | Tìm kiếm thống nhất | `--tool`, `--json` |
+| `health` | Kiểm tra khả dụng công cụ | — |
+| `score` | Chấm điểm chất lượng bằng chứng | `--threshold` |
+
+## Quy Trình Thường Gặp
+
+### Quy trình: Xác Thực Khẳng Định Kỹ Thuật
+
+1. Tìm kiếm bằng chứng cục bộ: `vds-cli research search "nội dung khẳng định"`
+2. Truy vấn nguồn bên ngoài: `vds-cli research search "chủ đề" --tool tavily`
+3. Thu thập và tổ chức phát hiện
+4. Chấm điểm chất lượng bằng chứng
+5. Xuất báo cáo sẵn sàng quyết định
+
+## Liên Quan
+
+- **Điều phối viên:** [memory](memory-orchestrator.md), [spec](spec-orchestrator.md), [audit](audit-triage-playbook.md)
+- **Skill:** [research-skill](../../../../vds-skills/skills/research-skill/SKILL.md)
+- **Confluence:** [WHO Research](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/schema-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/schema-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)
+
+# Schema orchestrator
+
+> Chuyển đổi schema markdown sang Prisma, TypeORM, PlantUML, Mermaid, SQL DDL, JSON Schema.
+
+## Phạm vi
+
+- **Làm:** Chuyển đổi định nghĩa schema giữa các định dạng, xác thực theo chuẩn, sinh script migration và tạo sơ đồ ER.
+- **Không làm:** Thiết kế schema từ đầu, thay thế công cụ ORM, hoặc quản lý migration database.
+- **Người dùng chính:** AI agent (sinh mã), nhà phát triển (chuyển đổi schema), DBA.
+
+## Điểm vào CLI
+
+```bash
+# Qua router thống nhất
+vds-cli schema --help
+
+# Direct entry
+vds-cli schema-convert --help
+```
+
+## Lệnh chính
+
+| Lệnh | Mục đích | Flag thường dùng |
+|------|----------|------------------|
+| `convert` | Chuyển đổi định dạng schema | `--input`, `--output`, `--target` |
+| `validate` | Xác thực schema | `--input`, `--standard` |
+| `generate` | Sinh mã từ schema | `--input`, `--language`, `--output` |
+| `diagram` | Sinh sơ đồ ER | `--input`, `--format` |
+
+## Quy trình thường gặp
+
+### Quy trình: Markdown sang Prisma
+
+1. Định nghĩa schema trong markdown kèm frontmatter
+2. Chạy `vds-cli schema-convert convert --input schema.md --target prisma --output schema.prisma`
+3. Rà soát Prisma schema vừa sinh
+4. Chạy `prisma validate` để kiểm chứng
+
+### Quy trình: Sinh sơ đồ ER
+
+1. Chạy `vds-cli schema-convert diagram --input schema.md --format mermaid`
+2. Render bằng mermaid-cli hoặc nhúng vào docs
+
+## Liên quan
+
+- **Orchestrators:** [openapi](openapi-orchestrator.md), [diagrams](diagrams-orchestrator.md), [db-query](db-query-orchestrator.md)
+- **Confluence:** [WHO Schema](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Xử lý sự cố
+
+| Sự cố | Nguyên nhân | Cách khắc phục |
+|-------|-------------|----------------|
+| Command not found | Orchestrator chưa được cài | Chạy `uv sync --all-packages` |
+| Config missing | `~/.vds/.env` chưa được cấu hình | Thêm credentials theo [AGENTS.md](../../../AGENTS.md) |
+| Permission denied | Quyền truy cập không đủ | Kiểm tra token scope Bitbucket/Confluence |

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/search-tools.md

@@ -0,0 +1,19 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Search Tools
+
+Preferred search stack for the WHO workspace:
+
+- `rg` for fast text and file discovery
+- `sg` for structural search
+- `grepai` for semantic discovery when lexical search is insufficient
+- `code-review-graph` for structural graph analysis after the target local Git repo is already known and caller/callee/import/blast-radius context is the real need
+
+## Sources
+
+- [grepai-skill](../../../../vds-skills/skills/grepai-skill/SKILL.md)
+- [Advanced patterns](../../../../vds-skills/skills/grepai-skill/references/advanced-patterns.md)
+- [grepai commands](../../../../vds-skills/skills/grepai-skill/references/grepai-commands.md)
+iew-graph-skill/references/usage-notes-2026-03-18.md)

package/skills/vds-skill/vds-scripts/docs/vi/agents/reference/skills-reference.md

@@ -0,0 +1,27 @@
+<!-- diátaxis: reference -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Skills Reference
+
+The canonical skills catalog is:
+
+- [WHO skills catalog](../../../../vds-skills/README.md)
+
+Key operational skills:
+
+- [vds-scripts-skill](../../../../vds-skills/skills/vds-scripts-skill/SKILL.md) — platform-routing entrypoint for the WHO scripts ecosystem
+- [WHO capability routing matrix](who-capability-routing-matrix.md) — human/agent routing aid for command families and skill ownership
+- [audit-orchestrator-skill](../../../../vds-skills/skills/audit-orchestrator-skill/SKILL.md) — deep audit workflow execution and interpretation
+- [spec-creation-skill](../../../../vds-skills/skills/spec-creation-skill/SKILL.md) — spec creation and consolidation
+- [research-skill](../../../../vds-skills/skills/research-skill/SKILL.md) — source-backed research
+- [code-review-graph-skill](../../../../vds-skills/skills/code-review-graph-skill/SKILL.md) — structural graph companion analysis
+- [llm-analysis-skill](../../../../vds-skills/skills/llm-analysis-skill/SKILL.md) — LLM-backed content evaluation
+- [lsp-skill](../../../../vds-skills/skills/lsp-skill/SKILL.md) — LSP setup and usage
+- [circular-dependency-skill](../../../../vds-skills/skills/circular-dependency-skill/SKILL.md) — dependency-cycle analysis
+
+Guidance:
+- use `vds-scripts-skill` first for platform routing and command-family selection,
+- use specialist skills for deep workflow/runbook guidance,
+- prefer `rg` / direct file reads first for simple exact answers,
+- do not treat graph output as authoritative audit evidence.