@ngocsangairvds/vsaf 4.0.5 → 4.0.7

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

@@ -0,0 +1,53 @@
+<!-- diátaxis: reference -->
+
+# Research Orchestrator
+
+> Evidence-first technical research combining local repository evidence with external sources.
+
+## Scope
+
+- **Does:** Search local code (rg, sg, grepai), query external APIs (Tavily, Exa, Context7), score evidence, generate research packets.
+- **Does NOT:** Make decisions for you, replace human judgment on strategic choices.
+- **Primary users:** AI agents (fact validation), human leads (technology evaluation).
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli research --help
+
+# Direct entry
+vds-cli research --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `search` | Unified search | `--tool`, `--json` |
+| `health` | Check tool availability | — |
+| `score` | Score evidence quality | `--threshold` |
+
+## Common Workflows
+
+### Workflow: Validate Technical Claim
+
+1. Search local evidence: `vds-cli research search "claim text"`
+2. Query external sources: `vds-cli research search "topic" --tool tavily`
+3. Collect and organize findings
+4. Score evidence quality
+5. Emit decision-ready report
+
+## Related
+
+- **Orchestrators:** [memory](memory-orchestrator.md), [spec](spec-orchestrator.md), [audit](audit-triage-playbook.md)
+- **Skills:** [research-skill](../../../../vds-skills/skills/research-skill/SKILL.md)
+- **Confluence:** [WHO Research](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
+| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
+| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -0,0 +1,57 @@
+<!-- diátaxis: reference -->
+
+# Schema Orchestrator
+
+> Convert markdown schemas to Prisma, TypeORM, PlantUML, Mermaid, SQL DDL, JSON Schema.
+
+## Scope
+
+- **Does:** Convert schema definitions between formats, validate against standards, generate migration scripts, and produce ER diagrams.
+- **Does NOT:** Design schemas from scratch, replace ORM tooling, or manage database migrations.
+- **Primary users:** AI agents (code generation), developers (schema conversion), DBAs.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli schema --help
+
+# Direct entry
+vds-cli schema-convert --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `convert` | Convert schema format | `--input`, `--output`, `--target` |
+| `validate` | Validate schema | `--input`, `--standard` |
+| `generate` | Generate code from schema | `--input`, `--language`, `--output` |
+| `diagram` | Generate ER diagram | `--input`, `--format` |
+
+## Common Workflows
+
+### Workflow: Markdown to Prisma
+
+1. Define schema in markdown with frontmatter
+2. Run `vds-cli schema-convert convert --input schema.md --target prisma --output schema.prisma`
+3. Review generated Prisma schema
+4. Run `prisma validate` to verify
+
+### Workflow: Generate ER Diagram
+
+1. Run `vds-cli schema-convert diagram --input schema.md --format mermaid`
+2. Render with mermaid-cli or embed in docs
+
+## Related
+
+- **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)
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
+| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
+| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -0,0 +1,34 @@
+<!-- diátaxis: reference -->
+
+# Search Tools Reference
+
+> Available search tools in the VDS ecosystem and when to use each.
+
+## Tool Escalation Ladder
+
+| I know... | Tool | Example | When to escalate |
+|-----------|------|---------|-----------------|
+| Exact string | `rg` | `rg "UserAuthError" --type py` | No results → `sg` |
+| Code shape | `sg` | `sg -p 'class $N(BaseModel)' -l python` | No results → `grepai` |
+| Concept/meaning | `grepai` | `grepai search "auth middleware"` | Too many → scope it |
+| Caller chain | `graphify` | `graphify query "auth flow"` | No graph → `gitnexus` |
+| Prior decisions | `vds-cli memory` | `vds-cli memory search "retry pattern"` | No results → proceed fresh |
+
+## Commands
+
+```bash
+# Quick exact-string search
+rg "pattern" --type py
+
+# Semantic code search
+grepai search "credential resolution"
+
+# Architecture query
+graphify query "audit state management"
+```
+
+## Related
+
+- [Research Orchestrator](research-orchestrator.md)
+- [Memory Orchestrator](memory-orchestrator.md)
+- [VDS CLI](vds-cli-reference.md)

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

@@ -0,0 +1,256 @@
+<!-- diátaxis: reference -->
+
+# Skills Commands Reference
+
+> Unified VDS skill management via `vds-cli skills`. Delegates to `vds-skills-sync`.
+
+## Summary Box
+
+| Property | Value |
+|---|---|
+| Command family | `vds-cli skills` |
+| Underlying package | `vds-skills-sync` (sibling repo) |
+| Delegation mode | Subprocess (`python -m vds_skills_sync`) |
+| Source file | `vds_cli/src/vds_cli/skills_cmd.py` |
+| Target agents | Claude Code, Cursor, Copilot, generic |
+
+**Important:** This command family is a thin wrapper. It does not import `vds-skills-sync`; it resolves the package path, injects it into `PYTHONPATH`, and spawns a subprocess. Exit codes and stdout/stderr are forwarded verbatim.
+
+## Table of Contents
+
+- [Quick Reference](#quick-reference)
+- [Subcommands](#subcommands)
+  - [sync](#sync)
+  - [list](#list)
+  - [validate](#validate)
+  - [info](#info)
+  - [rollback](#rollback)
+  - [version](#version)
+- [Environment](#environment)
+- [Exit Codes](#exit-codes)
+- [See Also](#see-also)
+
+## Quick Reference
+
+| Subcommand | Purpose | Key Flags | Example |
+|---|---|---|---|
+| `sync` | Install skills to an AI agent | `--agent`, `--dry-run`, `--skills`, `--exclude-skills`, `--diff` | `vds-cli skills sync --agent cursor --dry-run` |
+| `list` | List all registry skills | (none) | `vds-cli skills list` |
+| `validate` | Check skills against the AgentSkills spec | `--skill`, `--all`, `--strict`, `--fix`, `--json` | `vds-cli skills validate --all --strict` |
+| `info` | Show rendered content for one skill | `NAME` (positional) | `vds-cli skills info audit-orchestrator-skill` |
+| `rollback` | Restore skills from the most recent backup | (none) | `vds-cli skills rollback` |
+| `version` | Show vds-skills-sync package version | (none) | `vds-cli skills version` |
+
+## Subcommands
+
+### sync
+
+Install or update VDS skills for a target AI agent.
+
+```bash
+vds-cli skills sync [OPTIONS]
+```
+
+#### Flags
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--agent`, `-a` | string | `claude` | Target agent: `claude`, `cursor`, `copilot`, `generic`, `all` |
+| `--dry-run` | bool | `False` | Preview changes without writing files |
+| `--force` | bool | `False` | Skip validation checks before sync |
+| `--scope` | string | `project` | Installation scope: `project` or `user` (affects Cursor) |
+| `--skills` | string | `""` | Comma-separated skill names to sync. **Mutually exclusive with `--exclude-skills`.** |
+| `--exclude-skills` | string | `""` | Comma-separated skill names to exclude. **Mutually exclusive with `--skills`.** |
+| `--category` | string | `""` | Comma-separated categories to filter skills |
+| `--diff` | bool | `False` | Show structured diff (requires `--dry-run`) |
+| `--diff-format` | string | `summary` | Diff output format: `summary`, `unified`, or `json` |
+
+#### Example: dry-run with diff
+
+```bash
+vds-cli skills sync --agent claude --dry-run --diff --diff-format unified
+```
+
+#### Example: sync specific skills
+
+```bash
+vds-cli skills sync --agent copilot --skills "audit-orchestrator-skill,spec-creation-skill"
+```
+
+#### Example: sync all except excluded
+
+```bash
+vds-cli skills sync --agent generic --exclude-skills "legacy-migration-skill"
+```
+
+#### Mutual Exclusion
+
+Passing both `--skills` and `--exclude-skills` raises a `typer.BadParameter` error before delegation.
+
+---
+
+### list
+
+List every skill declared in the VDS registry.
+
+```bash
+vds-cli skills list
+```
+
+#### Flags
+
+This subcommand accepts no wrapper-level flags. Output formatting is determined by the underlying `vds-skills-sync` package.
+
+#### Example
+
+```bash
+vds-cli skills list
+```
+
+---
+
+### validate
+
+Validate VDS skills against the AgentSkills specification.
+
+```bash
+vds-cli skills validate [OPTIONS]
+```
+
+#### Flags
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--skill`, `--validate-skill` | path | `None` | Validate a single `SKILL.md` file by path |
+| `--all`, `--validate-all` | bool | `False` | Validate every registry-declared skill (default when no target given) |
+| `--strict` | bool | `False` | Promote quality warnings to errors |
+| `--fix` | bool | `False` | Auto-correct trivial issues in-place |
+| `--output`, `-o` | path | `None` | Write audit report to `PATH` |
+| `--json` | bool | `False` | Output JSON instead of human-readable text |
+
+#### JSON Output Caveat
+
+When invoked via this CLI wrapper, JSON output may include header lines on stdout. To extract clean JSON, pipe through a filter:
+
+```bash
+vds-cli skills validate --all --json | python -c 'import json,sys; [print(l) for l in sys.stdin if l.strip().startswith(("{","["))]'
+```
+
+#### Example: validate all skills strictly
+
+```bash
+vds-cli skills validate --all --strict
+```
+
+#### Example: validate one file and write a report
+
+```bash
+vds-cli skills validate --skill ./skills/my-skill/SKILL.md --output ./audit-report.txt
+```
+
+#### Example: auto-fix and validate
+
+```bash
+vds-cli skills validate --all --fix --strict
+```
+
+---
+
+### info
+
+Show the rendered content for a single skill.
+
+```bash
+vds-cli skills info NAME
+```
+
+#### Arguments
+
+| Argument | Type | Description |
+|---|---|---|
+| `NAME` | string | Skill name, e.g. `audit-orchestrator-skill` |
+
+#### Example
+
+```bash
+vds-cli skills info audit-orchestrator-skill
+```
+
+---
+
+### rollback
+
+Restore skills from the most recent backup.
+
+```bash
+vds-cli skills rollback
+```
+
+#### Flags
+
+This subcommand accepts no wrapper-level flags or arguments.
+
+#### Safety Notes
+
+- Rollback operates on the backup created by the most recent successful `sync`.
+- If no backup exists, the underlying package exits non-zero.
+- Always run `vds-cli skills sync --dry-run` before a destructive sync if you need a predictable restore point.
+
+#### Example
+
+```bash
+vds-cli skills rollback
+```
+
+### version
+
+Show the installed version of the `vds-skills-sync` package.
+
+```bash
+vds-cli skills version
+```
+
+**Example output:**
+
+```
+vds-skills-sync 0.7.3
+```
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `VDS_SKILLS_SYNC_DIR` | Overrides the path to the `vds-skills-sync` package. Must contain `src/vds_skills_sync/__init__.py`. |
+| `PYTHONPATH` | The wrapper prepends the resolved `vds-skills-sync/src` directory to the existing value (if any) before spawning the subprocess. |
+
+### Path Resolution
+
+The wrapper resolves the `vds-skills-sync` package in this order:
+
+1. `VDS_SKILLS_SYNC_DIR` environment variable.
+2. Walk up from `skills_cmd.py` until `WHO-project/vds-skills/vds-skills-sync` is found.
+3. If neither succeeds, raise `RuntimeError`.
+
+## Exit Codes
+
+| Subcommand | Code | Meaning |
+|---|---|---|
+| **Any** | `0` | Success |
+| **Any** | `1` | General validation or runtime error (forwarded from `vds-skills-sync`) |
+| **Any** | `2` | Strict quality failure (`--strict` set) |
+| **sync** | `1` | Invalid flag combination (e.g. `--skills` + `--exclude-skills`) or downstream sync error |
+| **validate** | `1` | Validation errors or invalid flag combination (e.g. `--skill` + `--all`) |
+| **validate** | `2` | Quality warnings promoted to errors by `--strict` |
+| **list / info / rollback** | `1` | Downstream error (forwarded from `vds-skills-sync`) |
+
+## See Also
+
+- [AGENTS.md](../../../../AGENTS.md) — high-level agent entry point
+- `vds-skills-sync` spec — `.gpt-5.4/specs/vds-skills-sync/`
+- [VDS CLI Reference](vds-cli-reference.md) — command-family routing
+- [Skills Reference](skills-reference.md) — canonical skills catalog
+- [CLI Help Matrix](cli-help-matrix.md) — verified routed command inventory
+
+---
+
+*Generated from `skills_cmd.py` (Phase 179). Do not modify flag semantics without updating both the source and this document.*

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

@@ -0,0 +1,32 @@
+<!-- diátaxis: reference -->
+
+# 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.
+
+## Related Documents
+
+- [VDS CLI Reference](vds-cli-reference.md)
+- [Orchestrator Index](orchestrator-index.md)
+- [Skills Reference](skills-reference.md)
+- [Confluence Hub](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

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

@@ -0,0 +1,62 @@
+<!-- diátaxis: reference -->
+
+# SonarQube Orchestrator
+
+> SonarQube code quality scanning and issue management for VDS repositories.
+
+## Scope
+
+- **Does:** Query SonarQube projects, list issues and hotspots, run health checks, and export quality metrics.
+- **Does NOT:** Execute scans (requires Maven or sonar-scanner in PATH), manage SonarQube server configuration.
+- **Primary users:** AI agents (quality gate checks), developers (issue triage).
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli sonarqube --help
+
+# Direct entry
+vds-cli sonarqube --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `ping` | Test connectivity and authentication | — |
+| `projects` | List accessible SonarQube projects | `--query`, `--limit` |
+| `issues` | List issues for a project | `--project`, `--status`, `--severity` |
+| `hotspots` | List security hotspots | `--project`, `--status` |
+| `measures` | Get quality measures for a project | `--project`, `--metrics` |
+
+## Workflow Examples
+
+```bash
+# Health check
+vds-cli sonarqube ping
+
+# List projects
+vds-cli sonarqube projects --limit 50
+
+# List open issues for a project
+vds-cli sonarqube issues list --project ekyc-business --status OPEN
+
+# List high-severity issues
+vds-cli sonarqube issues list --project ekyc-business --severity CRITICAL,BLOCKER
+
+# Get quality measures
+vds-cli sonarqube measures --project ekyc-business --metrics coverage,bugs,vulnerabilities
+
+# JSON-only output
+vds-cli sonarqube --json-only ping
+```
+
+## Configuration
+
+Requires `VDS_SONAR_TOKEN` or `VDS_SONAR_USER`/`VDS_SONAR_PASSWORD` in `~/.vds/.env`.
+
+## Related
+
+- **Orchestrators:** [grafana](grafana-orchestrator.md), [elastic](elastic-orchestrator.md)
+- **Confluence:** [WHO SonarQube](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

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

@@ -0,0 +1,56 @@
+<!-- diátaxis: reference -->
+
+# Spec Orchestrator
+
+> Create, validate, and maintain canonical VDS specification triplets.
+
+## Scope
+
+- **Does:** Scaffold spec directories, validate triplet consistency, check alignment between requirements/design/tasks, enforce AGENTS.md sync lines.
+- **Does NOT:** Write spec content for you, auto-generate designs from thin air, replace human review.
+- **Primary users:** AI agents (spec creation), human leads (review and approval).
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli spec --help
+
+# Direct entry
+vds-cli spec --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `validate <path>` | Validate a spec triplet | — |
+| `check-alignment <path>` | Cross-reference FRs and tasks | — |
+| `validate-sync <name>` | Sync-check with AGENTS.md | `--agents-label` |
+| `create <name>` | Scaffold new spec directory | — |
+
+## Common Workflows
+
+### Workflow: Create New Phase Spec
+
+1. Define scope and acceptance criteria
+2. Run `vds-cli spec create <name>` to scaffold triplet
+3. Fill in `requirements.md`, `design.md`, `tasks.md`
+4. Run `vds-cli spec validate <path>` to verify structure
+5. Run `vds-cli spec check-alignment <path>` to cross-reference
+6. Update AGENTS.md sync line
+7. Run `vds-cli spec validate-sync <name> --agents-label "..."`
+
+### Workflow: Validate Existing Spec
+
+1. Run `vds-cli spec validate <path>` — checks version alignment, FR presence, task packages
+2. Run `vds-cli spec check-alignment <path>` — verifies FR/task cross-references
+3. Fix any reported gaps
+4. Re-run until all checks pass
+
+## Related
+
+- **Orchestrators:** [tasks](tasks-orchestrator.md), [audit](audit-triage-playbook.md), [research](research-orchestrator.md)
+- **Skills:** [spec-creation-skill](../../../../vds-skills/skills/spec-creation-skill/SKILL.md)
+- **Confluence:** [WHO Specs](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
+- **Bitbucket:** [vds-scripts source](https://bitbucket.digital.vn/projects/WHO/repos/vds-scripts/browse)

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

@@ -0,0 +1,69 @@
+<!-- diátaxis: reference -->
+
+# Structure Orchestrator
+
+> Structure validation for VDS documentation and project folder consistency.
+
+## Scope
+
+- **Does:** Validate target-state documentation structure, check folder consistency across projects, and generate structure compliance reports.
+- **Does NOT:** Create missing folders automatically or validate file content.
+- **Primary users:** AI agents (docs readiness checks), project maintainers.
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli structure --help
+
+# Direct entry
+vds-structure --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `validate` | Validate structure (target-state or folder consistency) | `--mode`, `--root`, `--report` |
+
+## Validation Modes
+
+- `target-state` — validate target-state documentation tree structure
+- `folder-consistency` — compare folder structures across projects and score consistency
+
+## Workflow Examples
+
+```bash
+# Validate target-state structure
+vds-structure validate --mode target-state
+
+# Validate with custom root
+vds-structure validate --mode target-state --root ./docs
+
+# Folder consistency check across projects
+vds-structure validate --mode folder-consistency --root ./projects
+
+# Write JSON report
+vds-structure validate --mode target-state --report structure-report.json
+
+# JSON-only output
+vds-structure --json-only validate --mode target-state
+```
+
+## Report Output
+
+Folder consistency reports include:
+- Total and analyzed project counts
+- Consistency score (percentage)
+- Missing projects list
+- Common folders and files
+- Per-project mismatch details
+
+## Environment
+
+- `VDS_INSURANCE_DOCS_ROOT` — override default documentation root discovery
+
+## Related
+
+- **Orchestrators:** [links](links-orchestrator.md), [brd](brd-orchestrator.md)
+- **Confluence:** [WHO Structure](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

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

@@ -0,0 +1,76 @@
+<!-- diátaxis: reference -->
+
+# System Requirements
+
+## Required
+
+| Component | Version | Check Command |
+|-----------|---------|---------------|
+| Python | 3.14+ | `python3 --version` |
+| uv | Latest | `uv --version` |
+| Git | 2.40+ | `git --version` |
+| Docker | 24.0+ | `docker --version` |
+| Docker Compose | 2.20+ | `docker compose version` |
+
+## Optional
+
+| Component | Purpose | Check Command |
+|-----------|---------|---------------|
+| VS Code | Recommended IDE | `code --version` |
+| fzf | Fuzzy finder for shell | `fzf --version` |
+| ripgrep (rg) | Fast search | `rg --version` |
+| tree | Directory visualization | `tree --version` |
+
+## Platform Support
+
+| OS | Status | Notes |
+|----|--------|-------|
+| macOS | Supported | Apple Silicon and Intel |
+| Linux | Supported | Ubuntu 22.04+, Rocky Linux 9+ |
+| Windows | Not supported | Use WSL2 |
+
+## Services (Docker)
+
+| Service | Port | Image |
+|---------|------|-------|
+| Postgres | 5432 | postgres:16 |
+| Redis | 6379 | redis:7 |
+| Qdrant | 6333 | qdrant/qdrant |
+
+## Verify Everything
+
+```bash
+# Run all checks
+python3 --version && uv --version && git --version && docker --version
+
+# Check running services
+docker compose ps
+```
+
+## See Also
+
+- [Quick Start](../tutorials/quick-start.md)
+- [Configuration Reference](../reference/configuration-reference.md)
+
+## Verification Workflow
+
+Run this checklist before first `vds-cli` use:
+```bash
+# Core toolchain
+python3 --version  # Expected: 3.14+
+uv --version
+
+# Container runtime
+docker compose version
+docker compose ps  # Verify Postgres/Redis/Qdrant are healthy
+
+# Repository
+python3 -c "import uuid; print('Python OK')"
+uv sync  # Reproducible install
+```
+
+## See Also
+
+- [Quick Start](../tutorials/quick-start.md)
+- [Configuration Reference](../reference/configuration-reference.md)
+- [Troubleshooting Guide](../how-to/troubleshooting-guide.md)