@ngocsangairvds/vsaf 3.1.27 → 3.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.1.27",
-  "description": "improve confluence format",
+  "version": "3.2.2",
+  "description": "add vds script env",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "superpowers"],
   "bin": {
     "vsaf": "./bin/vsaf.js"

package/src/global.js

@@ -4,20 +4,20 @@ const fs = require('fs');
 const readline = require('readline');
 const { ok, info, warn, step, hasCommand, exec, copyDir, copyFile, CLAUDE_HOME, CODEX_HOME } = require('./utils');
 
-const PKG_ROOT        = path.join(__dirname, '..');
-const SKILLS_SRC      = path.join(PKG_ROOT, 'tools', 'skills');
-const SKILLS_DST      = path.join(CLAUDE_HOME, 'skills');
+const PKG_ROOT = path.join(__dirname, '..');
+const SKILLS_SRC = path.join(PKG_ROOT, 'tools', 'skills');
+const SKILLS_DST = path.join(CLAUDE_HOME, 'skills');
 const CODEX_SKILLS_DST = path.join(CODEX_HOME, 'skills');
 
 async function installGlobal() {
   console.log('\n\x1b[1m╔══════════════════════════════════════════╗\x1b[0m');
-  console.log(  '\x1b[1m║   VSAF — Global Infra                    ║\x1b[0m');
-  console.log(  '\x1b[1m╚══════════════════════════════════════════╝\x1b[0m');
+  console.log('\x1b[1m║   VSAF — Global Infra                    ║\x1b[0m');
+  console.log('\x1b[1m╚══════════════════════════════════════════╝\x1b[0m');
 
   installSkills();
   installBinary('gitnexus', () => exec('npm install -g gitnexus@1.6.4-rc.79'));
   setupGitnexusMcp();
-  await setupConfluenceMcp();
+  await setupVdsScriptsMcp();
 
   console.log('\n\x1b[32m\x1b[1m✓ Global infra ready.\x1b[0m\n');
 }
@@ -71,49 +71,75 @@ function setupGitnexusMcp() {
     : warn('MCP setup failed — run manually: claude mcp add gitnexus -- npx -y gitnexus@1.6.4-rc.79 mcp');
 }
 
-async function setupConfluenceMcp() {
-  step('Confluence MCP');
+
+
+async function setupVdsScriptsMcp() {
+  step('VDS Scripts MCP');
 
   if (!hasCommand('claude')) {
-    info('Claude Code CLI not found — skip Confluence MCP setup');
+    info('Claude Code CLI không tìm thấy — bỏ qua thiết lập VDS MCP');
     return;
   }
 
-  const url = await promptInput(
-    '  Confluence URL (blank to skip, e.g. http://confluence.company.com): '
-  );
-
-  if (!url) {
-    warn('Confluence MCP skipped — run manually later:\n' +
-         '    claude mcp add confluence -e CONF_MODE=server \\\n' +
-         '      -e CONF_BASE_URL=<your-url> \\\n' +
-         '      -e CONF_AUTH_MODE=bearer \\\n' +
-         '      -e CONF_TOKEN=<your-token> \\\n' +
-         '      -- npx -y confluence-mcp-server');
+  const srcDir = path.join(PKG_ROOT, 'tools', 'vds-scripts');
+  const destDir = path.join(CLAUDE_HOME, 'vds-scripts');
+  const mcpDir = path.join(destDir, 'mcp_server');
+
+  info(`Source: ${srcDir}`);
+  if (!fs.existsSync(srcDir)) {
+    warn('Không tìm thấy source vds-scripts trong package — bỏ qua cài đặt.');
     return;
   }
 
-  const token = await promptSecret(
-    '  Confluence Personal Access Token: '
-  );
-
-  if (!token) {
-    warn('Confluence MCP skipped — token is required');
-    return;
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
+  copyDir(srcDir, destDir);
+  ok('Cài đặt thành công.');
+
+  step('Cấu hình VDS CLI và Credentials');
+  const envDir = path.join(require('os').homedir(), '.vds');
+  const envFile = path.join(envDir, '.env');
+  if (!fs.existsSync(envFile)) {
+    fs.mkdirSync(envDir, { recursive: true });
+
+    info('Vui lòng cung cấp các thông tin xác thực sau (Bắt buộc):');
+    let vdsUsername = ''; while (!vdsUsername) vdsUsername = await promptInput('  Nhập VDS_USERNAME: ');
+    let vdsPassword = ''; while (!vdsPassword) vdsPassword = await promptSecret('  Nhập VDS_PASSWORD: ');
+    let bitbucketToken = ''; while (!bitbucketToken) bitbucketToken = await promptSecret('  Nhập BITBUCKET_TOKEN: ');
+    let jiraToken = ''; while (!jiraToken) jiraToken = await promptSecret('  Nhập JIRA_TOKEN: ');
+    let confluenceToken = ''; while (!confluenceToken) confluenceToken = await promptSecret('  Nhập INTERNAL_CONFLUENCE_TOKEN: ');
+    let extConfluenceToken = ''; while (!extConfluenceToken) extConfluenceToken = await promptSecret('  Nhập EXTERNAL_CONFLUENCE_TOKEN: ');
+
+    let jiraBaseUrl = ''; while (!jiraBaseUrl) jiraBaseUrl = await promptInput('  Nhập JIRA_BASE_URL (e.g. https://jira.viettelmoney.vn/): ');
+    let bitbucketBaseUrl = ''; while (!bitbucketBaseUrl) bitbucketBaseUrl = await promptInput('  Nhập BITBUCKET_BASE_URL (e.g. http://bitbucket.digital.vn): ');
+    let confluenceInternalUrl = ''; while (!confluenceInternalUrl) confluenceInternalUrl = await promptInput('  Nhập CONFLUENCE_INTERNAL_URL (e.g. http://10.254.136.35:8090): ');
+    let confluenceExternalUrl = ''; while (!confluenceExternalUrl) confluenceExternalUrl = await promptInput('  Nhập CONFLUENCE_EXTERNAL_URL (e.g. http://10.254.136.35:8090): ');
+
+    const envContent = [
+      `VDS_USERNAME=${vdsUsername}`,
+      `VDS_PASSWORD=${vdsPassword}`,
+      `BITBUCKET_TOKEN=${bitbucketToken}`,
+      `JIRA_TOKEN=${jiraToken}`,
+      `INTERNAL_CONFLUENCE_TOKEN=${confluenceToken}`,
+      `EXTERNAL_CONFLUENCE_TOKEN=${extConfluenceToken}`,
+      `JIRA_BASE_URL=${jiraBaseUrl}`,
+      `CONFLUENCE_INTERNAL_URL=${confluenceInternalUrl}`,
+      `CONFLUENCE_EXTERNAL_URL=${confluenceExternalUrl}`,
+      `BITBUCKET_BASE_URL=${bitbucketBaseUrl}`
+    ].join('\n') + '\n';
+
+    fs.writeFileSync(envFile, envContent);
+    ok('Đã lưu cấu hình an toàn vào ~/.vds/.env');
+  } else {
+    ok('Đã tìm thấy file cấu hình ~/.vds/.env');
   }
 
-  const cmd = [
-    'claude mcp add confluence',
-    '-e CONF_MODE=server',
-    `-e CONF_BASE_URL=${url}`,
-    '-e CONF_AUTH_MODE=bearer',
-    `-e CONF_TOKEN=${token}`,
-    '-- npx -y confluence-mcp-server',
-  ].join(' ');
-
-  exec(cmd)
-    ? ok('Confluence MCP configured')
-    : warn('Confluence MCP setup failed — run manually (see above)');
+  const cmd = `claude mcp add vds-orchestrator -- uv run --project "${mcpDir}" vds-mcp-server`;
+
+  if (exec(cmd)) {
+    ok('VDS Scripts MCP đã được cấu hình thành công');
+  } else {
+    warn('Lỗi thiết lập MCP — vui lòng chạy lệnh thủ công');
+  }
 }
 
 function promptInput(question) {

package/tools/skills/vds-scripts-skill/.openskills.json

@@ -0,0 +1,6 @@
+{
+  "source": "./.agent/skills/vds-scripts-skill",
+  "sourceType": "local",
+  "localPath": "/Users/vds-ai/Library/Mobile Documents/com~apple~CloudDocs/project/vds/.agent/skills/vds-scripts-skill",
+  "installedAt": "2026-01-26T07:07:42.597Z"
+}

package/tools/skills/vds-scripts-skill/QUALITY.md

@@ -0,0 +1,44 @@
+# Quality Baseline — vds-scripts-skill
+
+## Version History
+
+| Version | Date | Score | Evaluator | Notes |
+|---------|------|-------|-----------|-------|
+| 1.0.0 | 2026-03-19 | 3.6/5 | Manual | Initial baseline - needs split |
+| 1.1.0 | 2026-03-23 | pending | Manual | Repositioned as platform-routing skill; pending post-refactor review |
+
+## Evaluation Criteria
+
+| Criterion | Weight | Type | Description |
+|-----------|--------|------|-------------|
+| Accuracy | 40% | Scored 1-5 | Commands and routing guidance are correct |
+| Completeness | 25% | Scored 1-5 | Current WHO capabilities are represented through skill text, references, or routing aids |
+| Actionability | 20% | Scored 1-5 | Users can quickly choose the correct command family or specialist skill |
+| Token Efficiency | 10% | Scored 1-5 | Main skill stays concise and relies on progressive disclosure |
+| Schema Validity | 5% | Binary | Skill follows AgentSkills/OpenSkills structure and metadata |
+
+## Current Role
+
+`vds-scripts-skill` is the platform-routing skill for the WHO scripts ecosystem.
+It is not the deep specialist runbook for audit workflows or other specialist domains.
+
+## Known Issues
+
+- Post-refactor scoring still needs a fresh baseline run.
+- Capability coverage should be validated against the current WHO workspace inventory.
+- Generated/root agent surfaces must be synced after the final skill/doc changes land.
+
+## Validation Checklist
+
+- [ ] `SKILL.md` remains concise and activation-oriented
+- [ ] references/ covers the broader capability map
+- [ ] routing matrix maps common intents to the right skill/command family
+- [ ] registry metadata matches the updated role
+- [ ] scripts docs and skills docs tell the same ownership story
+
+## Quality Hypotheses
+
+| Date | Hypothesis | Expected | Actual | Score Change |
+|------|------------|----------|--------|--------------|
+| 2026-03-23 | Shift from command dump to platform-routing + references | Token Efficiency up, Completeness up, clearer routing | pending | pending |
+| 2026-03-23 | Add capability index and routing matrix | Completeness 3.5→4.2 | pending | pending |

package/tools/skills/vds-scripts-skill/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: vds-scripts-skill
+description: Use the WHO VDS scripts ecosystem as the platform entrypoint for routed CLI commands, workspace capabilities, and skill delegation. Use when you need to choose the right vds-cli command family, understand the current WHO scripts surface, or route to the correct specialist skill.
+license: Apache-2.0
+metadata:
+  version: "1.1.0"
+  author: "VDS Platform Team"
+  category: "infrastructure"
+  tags:
+    - cli
+    - routing
+    - orchestrators
+    - platform
+    - who
+---
+
+# VDS Scripts Skill
+
+Use this skill as the **platform-routing entrypoint** for the WHO scripts ecosystem.
+
+`WHO-project` is the canonical VDS ecosystem for both reusable skills and routed scripts:
+- skills live under `WHO-project/vds-skills/skills/`
+- scripts and orchestrators live under `WHO-project/vds-scripts/`
+
+This skill helps you:
+- find the right `vds-cli` command family
+- understand the current WHO scripts workspace surface
+- identify whether a task belongs to a platform command or a specialist skill
+- route humans and AI agents to the correct authoritative source
+
+## When to Use
+
+Use this skill when you need:
+- a quick map of the WHO scripts ecosystem
+- the right command family for a task
+- the right specialist skill for deeper guidance
+- bootstrap guidance for `vds-cli`, environment checks, and command discovery
+- a capability index for current WHO automation surfaces
+
+Do **not** use this skill as the authoritative deep runbook for:
+- audit workflow execution → use `audit-orchestrator-skill`
+- LLM-backed content evaluation → use `llm-analysis-skill`
+- spec authoring/consolidation → use `spec-creation-skill`
+- LSP setup and type-checking workflows → use `lsp-skill`
+- circular dependency analysis → use `circular-dependency-skill`
+
+## Canonical Sources
+
+- Scripts workspace: `WHO-project/vds-scripts/`
+- Skills catalog: `WHO-project/vds-skills/skills/`
+- Skill registry: `WHO-project/vds-skills/registry.yaml`
+- Alignment workflow: `WHO-project/vds-skills/ALIGNMENT.md`
+
+## Primary Command Entry Points
+
+```/dev/null/vds-scripts-skill-entrypoints.sh#L1-12
+# Interactive monorepo-root usage
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli --help
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --help
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package spec_orchestrator vds-spec --help
+
+# Dedicated vds-scripts worktree usage
+./scripts/worktree_uv.sh run --package vds_cli vds-cli --help
+./scripts/worktree_uv.sh run --package audit_orchestrator vds-audit --help
+./scripts/worktree_uv.sh run --package spec_orchestrator vds-spec --help
+
+# Maintained shell scripts must not copy the plain patterns above.
+# They should source scripts/vds_sh_helpers.sh and use vds_uv_run_package
+# / vds_uv_sync_package / vds_uv_sync_all instead.
+```
+
+## Platform Command Families
+
+### Bootstrap and discovery
+- `vds-cli env ...`
+- `vds-cli status`
+- `vds-cli doctor`
+- `vds-cli docs ...`
+
+### Integrations
+- `vds-cli jira ...`
+- `vds-cli confluence ...`
+- `vds-cli bitbucket ...`
+- `vds-cli git ...`
+- `vds-cli elastic ...`
+- `vds-cli grafana ...`
+- `vds-cli sonarqube ...`
+
+### Documentation and validation
+- `vds-cli openapi ...`
+- `vds-cli links ...`
+- `vds-cli structure ...`
+- `vds-cli schema ...`
+- `vds-cli pdf ...`
+- `vds-cli diagrams ...`
+- `vds-cli excel ...`
+- `vds-cli google-sheets ...`
+- `vds-markdown ...` via `markdown_orchestrator`
+
+### Development and workflow
+- `vds-cli intellij ...`
+- `vds-cli tasks ...`
+- `vds-cli lsp ...`
+- `vds-cli spec ...`
+- `vds-cli audit ...`
+- `vds-cli circular-dependency ...`
+
+## Specialist Routing Map
+
+- Audit workflow execution and readiness gates → `audit-orchestrator-skill`
+- LLM-assisted doc/content scoring → `llm-analysis-skill`
+- Spec creation and consolidation → `spec-creation-skill`
+- CLI/orchestrator development standards → `cli-development-skill`
+- LSP configuration and usage → `lsp-skill`
+- Circular dependency analysis → `circular-dependency-skill`
+- Research-backed investigation → `research-skill`
+- Structural graph review → `code-review-graph-skill`
+
+## Progressive Disclosure
+
+Use these bundled references for depth:
+- `references/platform-bootstrap.md`
+- `references/capability-index.md`
+- `references/integration-commands.md`
+- `references/validation-commands.md`
+- `references/development-commands.md`
+- `references/specialist-routing.md`
+
+## Notes
+
+- Edit this skill only under `WHO-project/vds-skills/skills/vds-scripts-skill/`.
+- Do not edit `.agent/skills/` directly.
+- Keep this file concise and routing-oriented; push deeper command catalogs into `references/`.
+- For integrated `WHO-project/vds-scripts` workspace usage, Python 3.14+ is the preferred baseline for humans and AI agents.
+- After updates, sync generated agent surfaces from the monorepo root.

package/tools/skills/vds-scripts-skill/references/audit-commands.md

@@ -0,0 +1,171 @@
+# Audit Commands — VDS Scripts Skill
+
+Detailed command reference for audit orchestrator operations.
+
+These are interactive/operator command examples. From the umbrella monorepo root, prefer `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator ...`. Inside a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --package audit_orchestrator ...`. Maintained shell scripts inside `WHO-project/vds-scripts` should source `scripts/vds_sh_helpers.sh` instead of copying raw operator patterns. Preferred integrated baseline for the `vds-scripts` workspace is Python 3.14+.
+
+## Audit Prep Sequence (Hard-Cut State-First)
+
+```/dev/null/audit-commands-prep-sequence.sh#L1-20
+# 1) Seed centralized state from registry
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit parse-registry \
+  --registry-page "<REGISTRY_PAGE_URL_OR_ID>"
+
+# 2) Sync repositories for code evidence
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only sync repos \
+  --bitbucket-project "<BITBUCKET_PROJECT_KEY>" \
+  --project-storage-key "<PROJECT_STORAGE_KEY>"
+
+# 3) Materialize docs + code chunks
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit extract-docs \
+  --registry-page "<REGISTRY_PAGE_URL_OR_ID>" \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --output-dir "<EVIDENCE_DIR>"
+
+# 4) Hard gate before workflow
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only state readiness \
+  --project "<PROJECT_STORAGE_KEY>" --repo "<REPO_SELECTOR>" \
+  | jq '{ready, docs_chunk_ready, code_chunk_ready}'
+
+# 5) Phase 87 direct project/repo parsing
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only parse-project \
+  --project "<PROJECT_PAGE_ID>" > /tmp/parse-project.json
+
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit --json-only parse-repo \
+  --project "<PROJECT_PAGE_ID>" --bitbucket-project "<BITBUCKET_PROJECT_KEY>" \
+  --repo "<REPO_SELECTOR>" > /tmp/parse-repo.json
+
+# 6) Execute workflow with resolved repo seed
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit workflow "<LOCAL_REPO_PATH>" \
+  --thread-id "<THREAD_ID>" --canonical-checklist \
+  --checklist-profile "<PROFILE_ID>" \
+  --seed-payload /tmp/parse-repo.json
+```
+
+## Selector Notes
+
+- `parse-project` / `parse-repo` `--project` accepts only Confluence page-id selectors (numeric or URL with `pageId=<ID>`)
+- Checklist precedence: `--checklist-page-id` > `--checklist-profile` > state profile resolution > canonical fallback `88722450`
+- Phase 102 hard-cut: Legacy `CL-NNN:row_N` tokens not parsed; run `state migrate-row-keys --execute` first
+- Phase 90 selector isolation: `parse-project` rejects Bitbucket keys in `--project`; use `parse-repo --bitbucket-project`
+- `parse-repo` returns `repo_coverage` (project-wide) and `selected_repo_coverage` (filtered); use latter for single-repo seeds
+- `sync repos` selectors: `--local` > `--bitbucket-project` > `--github-org` > `--git-url` (precedence)
+
+## Audit Monitoring (Phase 68)
+
+```/dev/null/audit-commands-monitoring.sh#L1-11
+# Preflight credentials
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  --json-only doctor credentials --require-state-dsn
+
+# Dual-source prep gate
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  --json-only state readiness --project "<PROJECT_KEY>" --repo "<REPO_KEY>" \
+  | jq '{ready, docs_chunk_ready, code_chunk_ready, hierarchy_ready}'
+
+# Follow runtime logs
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  doctor logs-follow --follow --tail 200 --audit-id "<AUDIT_ID>" --json
+
+# Crawl diagnostics (Phase 80)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator vds-audit \
+  doctor crawl-status --project-storage-key "<PROJECT_KEY>"
+```
+
+## Corpus Lifecycle (Phase 94)
+
+```bash
+# Dry-run purge
+vds-audit --json-only corpus purge --project "<PROJECT_KEY>"
+
+# Execute purge with advisory lock
+vds-audit --json-only corpus purge --project "<PROJECT_KEY>" --execute
+
+# Keep latest, purge older
+vds-audit corpus purge --project "<PROJECT_KEY>" --keep-latest --execute
+
+# Backfill metadata
+vds-audit --json-only corpus backfill-metadata --project "<PROJECT_KEY>"
+
+# Health diagnostics
+vds-audit --json-only doctor corpus-status --project "<PROJECT_KEY>"
+
+# Force full re-ingest
+vds-audit extract-docs --project-storage-key "<PROJECT_KEY>" \
+  --force-full-reingest --execute
+```
+
+## DSPy Judge & Gold Dataset (Phase 108)
+
+DSPy is **enabled by default**. No `--use-dspy` flag needed.
+
+```bash
+# Workflow with DSPy judge (default)
+vds-audit workflow "<REPO_PATH>" --thread-id "<THREAD_ID>" --canonical-checklist
+
+# Disable DSPy explicitly
+vds-audit workflow "<REPO_PATH>" --thread-id "<THREAD_ID>" --canonical-checklist --no-use-dspy
+
+# Build gold dataset
+vds-audit build-gold-dataset [--search-root <dir>] [--output <path>] \
+  [--checklist-aware] [--category-balance] [--benchmark-slice]
+```
+
+**Key Environment Variables**:
+- `VDS_AUDIT_FEATURES__DSPY_ENABLED` (default: `true`)
+- `VDS_AUDIT_DSPY_JUDGE_MAX_INVOCATIONS_PER_RUN` (default: `20`)
+- `VDS_AUDIT_LLM__DSPY_JUDGE_LOW_CONFIDENCE_THRESHOLD` (default: `0.65`)
+- `VDS_AUDIT_DSPY_ASSERTIONS_ENABLED` (default: `true`)
+
+## Multi-Provider Runs (Phase 107)
+
+```/dev/null/audit-commands-multi-provider.sh#L1-21
+# Alibaba-openai (qwen3.5-plus)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile alibaba-openai \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+
+# Z.ai-openai (glm-5)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile zai-openai \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+
+# Gemini (via local proxy)
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package audit_orchestrator \
+  vds-audit workflow "<REPO_PATH>" \
+  --profile antigravity-gemini \
+  --project-storage-key "<PROJECT_STORAGE_KEY>" \
+  --thread-id "<THREAD_ID>" \
+  --canonical-checklist \
+  --target "CL-004,CL-001"
+```
+
+Non-Claude profiles have increased budgets: `MAX_TURNS=32`, `MAX_TOOL_CALLS=96`.
+
+For single-row reruns such as `CL-002`, keep the same workflow shape and pass `--target CL-002`. Do not use unsupported legacy selectors such as `--check-ids` or `--targeted-rows`.
+
+## System Documentation (Phase 106)
+
+```bash
+# Publish 6-page Vietnamese hierarchy
+vds-audit publish-system-doc --project "<PROJECT_ID>" --sync-policy if-changed
+
+# Force re-publish
+vds-audit publish-system-doc --project "<PROJECT_ID>" --sync-policy force
+```
+
+Hierarchy pages:
+- Root: Tài liệu Hệ thống Audit
+  - 📐 Công nghệ & Kiến trúc
+  - ⚙️ Quy trình Vận hành
+  - 📊 Kết quả Audit & Chỉ số
+  - 🔧 Hướng dẫn Cài đặt & Cấu hình
+  - 📖 Tham chiếu Kỹ thuật

package/tools/skills/vds-scripts-skill/references/capability-index.md

@@ -0,0 +1,34 @@
+# Capability Index
+
+This index maps the current WHO scripts ecosystem at a platform-routing level.
+
+## Routed command surfaces
+
+- bootstrap: `env`, `status`, `doctor`, `docs`
+- integrations: `jira`, `confluence`, `bitbucket`, `git`, `elastic`, `grafana`, `sonarqube`
+- docs/validation: `openapi`, `links`, `structure`, `schema`, `pdf`, `diagrams`, `excel`, `google-sheets`
+- development/workflow: `intellij`, `tasks`, `lsp`, `spec`, `audit`, `circular-dependency`
+
+## Standalone workspace capabilities
+
+- `markdown_orchestrator` for markdown lint/format workflows
+- `hexagonal_orchestrator` for architecture/compliance support
+- `mcp_server` for MCP/server-related support
+- `multi_agent_orchestrator` for multi-agent execution support
+
+## Shared/internal support layers
+
+- `vds_cli_common`
+- `vds_hooks`
+
+## Skills ecosystem linkage
+
+The WHO skills catalog complements the scripts workspace with specialist skills such as:
+- `audit-orchestrator-skill`
+- `llm-analysis-skill`
+- `spec-creation-skill`
+- `research-skill`
+- `lsp-skill`
+- `circular-dependency-skill`
+
+Use this index with `specialist-routing.md` and the scripts docs routing matrix.

package/tools/skills/vds-scripts-skill/references/development-commands.md

@@ -0,0 +1,12 @@
+# Development Commands
+
+Representative WHO development/workflow command families:
+
+- `vds-cli intellij ...`
+- `vds-cli tasks ...`
+- `vds-cli lsp ...`
+- `vds-cli spec ...`
+- `vds-audit ...`
+- `vds-cli circular-dependency ...`
+
+These families often route into specialist skills for deeper guidance.

package/tools/skills/vds-scripts-skill/references/google-sheets.md

@@ -0,0 +1,73 @@
+# Google Sheets Commands — VDS Scripts Skill
+
+Standalone package with 10 commands and full VDS CLI standards.
+
+## Commands
+
+```bash
+# List worksheets
+vds-cli google-sheets list-worksheets \
+  --spreadsheet-url <url> --auth-method service_account
+
+# Read a worksheet
+vds-cli google-sheets read \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --auth-method service_account
+
+# Read a limited range
+vds-cli google-sheets read \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range A1:F10
+
+# Write values to a range
+vds-cli google-sheets write \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range "A1:B2" \
+  --values-json '[["a","b"],["c","d"]]'
+
+# Append rows
+vds-cli google-sheets append \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --values-json '[["new","row"]]'
+
+# Clear a range
+vds-cli google-sheets clear \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --range "A1:Z100"
+
+# Create spreadsheet
+vds-cli google-sheets create-spreadsheet --title "New Spreadsheet"
+
+# Create worksheet
+vds-cli google-sheets create-worksheet \
+  --spreadsheet-url <url> --title "NewSheet" --rows 100 --cols 26
+
+# Delete worksheet
+vds-cli google-sheets delete-worksheet \
+  --spreadsheet-url <url> --sheet-name "SheetToDelete"
+
+# Export to CSV/XLSX
+vds-cli google-sheets export \
+  --spreadsheet-url <url> --sheet-name "Sheet1" --output data.csv --format csv
+
+# JSON output mode (all commands)
+vds-cli google-sheets -- --json-only read \
+  --spreadsheet-url <url> --sheet-name "Sheet1"
+```
+
+## Authentication
+
+**Defaults**:
+- Service account credentials: use the explicit path/config option when available; otherwise the active Unix-like default is `~/.vds/google_credentials.json`
+- API key: `VDS_GOOGLE_API_KEY` or, under the active Unix-like default, `~/.vds/google_api_key.txt`
+
+**Auth methods**:
+- `service_account` - Uses service account JSON file
+- `api_key` - Uses API key from env or file
+
+## Full Command Prefix
+
+Interactive monorepo-root usage commonly uses:
+
+```/dev/null/google-sheets-prefix.sh#L1-1
+./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package vds-cli vds-cli google-sheets <command>
+```
+
+Inside a dedicated `vds-scripts` worktree, the equivalent form is `./scripts/worktree_uv.sh run --package vds_cli vds-cli google-sheets <command>`.
+
+For maintained shell scripts inside `WHO-project/vds-scripts`, do not copy raw operator forms. Source `scripts/vds_sh_helpers.sh` and use the helper contract instead.

package/tools/skills/vds-scripts-skill/references/integration-commands.md

@@ -0,0 +1,17 @@
+# Integration Commands
+
+vds Representative WHO integration command families.
+
+These examples are interactive operator examples. From the umbrella monorepo root, prefer `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package <uv-package-name> ...`. Inside a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --package <member-dir> ...`. Maintained shell scripts inside `WHO-project/vds-scripts` should source `scripts/vds_sh_helpers.sh` instead of copying raw operator forms.
+
+- `vds-cli jira ...`
+  - JQL search example: `./WHO-project/vds-scripts/scripts/worktree_uv.sh run --directory WHO-project/vds-scripts --package jira_orchestrator vds-jira-cli search "project = CBDC ORDER BY updated DESC" --limit 5 --json-only`
+  - Note: `vds-jira-cli search` now accepts `--json-only` as a command-local flag after `search`, in addition to the global pre-subcommand form.
+- `vds-cli confluence ...`
+- `vds-cli bitbucket ...`
+- `vds-cli git ...`
+- `vds-cli elastic ...`
+- `vds-cli grafana ...`
+- `vds-cli sonarqube ...`
+
+Use the scripts workspace reference docs for deeper command examples.