@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/docs/agents/reference/cli-help-matrix.md

@@ -0,0 +1,84 @@
+<!-- diátaxis: reference -->
+
+# Verified CLI help matrix
+
+This reference helps AI agents and operators choose the correct VDS CLI entrypoint.
+**`vds-cli` is the ONLY valid user-facing entry point.** Direct package executables
+are internal router implementation details and must never be invoked by users.
+
+## How to use this matrix
+
+1. **Always** use routed `vds-cli <service> <command>` for all operations.
+2. **Never** invoke direct package executables (`vds-audit`, `vds-spec`, etc.) —
+   these are internal to the router.
+3. Treat `--help` as the authoritative discovery surface before assuming an
+   command name.
+4. In dedicated `vds-scripts` worktrees, prefer `./scripts/worktree_uv.sh ...`
+   for `uv` commands so inherited parent `VIRTUAL_ENV` state does not leak into
+   the wrong worktree.
+
+## Routed command families
+
+| Routed family | `vds-cli` form | Help status | Notes |
+| --- | --- | --- | --- |
+| platform | `vds-cli --help` | live-verified | Unified router entrypoint |
+| audit | `vds-cli audit ...` | live-verified | Specialist workflow surface |
+| spec | `vds-cli spec ...` | live-verified | Shared spec lifecycle tooling |
+| jira | `vds-cli jira ...` | live-verified | |
+| confluence | `vds-cli confluence ...` | live-verified | |
+| bitbucket | `vds-cli bitbucket ...` | live-verified | |
+| git | `vds-cli git ...` | live-verified | |
+| elastic | `vds-cli elastic ...` | live-verified | |
+| sonarqube | `vds-cli sonarqube ...` | live-verified | |
+| grafana | `vds-cli grafana ...` | live-verified | |
+| schema | `vds-cli schema ...` | live-verified | |
+| diagrams | `vds-cli diagrams ...` | live-verified | |
+| google-sheets | `vds-cli google-sheets ...` | live-verified | |
+| task management | `vds-cli tasks ...` | live-verified | |
+| openapi | `vds-cli openapi ...` | live-verified | |
+| pdf | `vds-cli pdf ...` | live-verified | |
+| markdown | `vds-cli markdown ...` | live-verified | Use `vds-cli markdown format` for formatting |
+| intellij | `vds-cli intellij ...` | live-verified | |
+| links | `vds-cli links ...` | live-verified | |
+| structure | `vds-cli structure ...` | live-verified | |
+| lsp | `vds-cli lsp ...` | live-verified | |
+| brd | `vds-cli brd ...` | live-verified | |
+| excel | `vds-cli excel ...` | live-verified | |
+| circular dependency | `vds-cli circular-dependency ...` | live-verified | |
+| progress | `vds-cli progress ...` | live-verified | |
+| hexagonal | `vds-cli hexagonal ...` | live-verified | |
+| multi-agent | `vds-cli multi-agent ...` | live-verified | |
+| public-interface | `vds-cli public-interface ...` | live-verified | |
+| metabase | `vds-cli metabase ...` | live-verified | |
+| mcp | `vds-cli mcp ...` | live-verified | |
+| research | `vds-cli research ...` | live-verified | |
+| scheduler | `vds-cli scheduler ...` | live-verified | VDS workflow scheduling |
+
+## Built-in commands
+
+Commands built into `vds-cli` (not routed to orchestrators):
+
+| Command | Purpose |
+| --- | --- |
+| `vds-cli status` | System status and health checks |
+| `vds-cli doctor` | Diagnose routing and environment readiness |
+| `vds-cli version` | Show VDS CLI version |
+| `vds-cli regenerate-manifest` | Regenerate repo-manifest.yaml from Bitbucket |
+
+## Worktree-safe examples
+
+> All examples **must** use `vds-cli` routing — direct executables are internal.
+
+- `./scripts/worktree_uv.sh run --project vds_cli vds-cli --help`
+- `./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --help`
+- `./scripts/worktree_uv.sh run --project vds_cli vds-cli spec --help`
+- `./scripts/worktree_uv.sh run --project vds_cli vds-cli tasks --help`
+- `./scripts/worktree_uv.sh run --project vds_cli vds-cli schema --help`
+
+## Source notes
+
+This matrix is maintained from:
+
+- live `--help` verification in the active Phase 3 worktree
+- Routed-family documentation in `vds_cli/README.md`, `cli-commands.md`, and `vds-cli-reference.md`
+- The canonical standard: `vds-cli` is the ONLY user-facing entry point

package/skills/vds-skill/runtime/docs/agents/reference/common-errors.md

@@ -0,0 +1,126 @@
+<!-- diátaxis: reference -->
+
+# Common Errors
+
+## CLI Errors
+
+### `ModuleNotFoundError: No module named 'xxx'`
+
+**Cause:** Dependency not installed or wrong venv.
+
+**Fix:**
+```bash
+uv sync
+source .venv/bin/activate
+```
+
+**Prevention:** Always run `uv sync` after pulling changes.
+
+### `subprocess.CalledProcessError: uv run ...`
+
+**Cause:** Orchestrator entry point not installed.
+
+**Fix:**
+```bash
+# Reinstall orchestrator
+cd <orchestrator_dir> && uv pip install -e .
+```
+
+**Prevention:** Run `uv sync` from vds-scripts root after any orchestrator changes.
+
+## Validation Errors
+
+### `ValidationError: 1 validation error for Settings`
+
+**Cause:** Missing or invalid environment variable.
+
+**Fix:**
+```bash
+# Check required vars
+vds-cli env status
+
+# Set missing var
+export CONFLUENCE_INTERNAL_URL=https://confluence.example.com
+```
+
+**Prevention:** Use the annotated `~/.vds/.env` template from [Configuration Reference](../reference/configuration-reference.md).
+
+## Database Errors
+
+### `Connection refused: postgres:5432`
+
+**Cause:** Postgres container not running.
+
+**Fix:**
+```bash
+docker compose up -d postgres
+```
+
+**Prevention:** Add `docker compose ps` to your startup checklist.
+
+### `sqlalchemy.exc.ProgrammingError: relation "xxx" does not exist`
+
+**Cause:** Schema not initialized.
+
+**Fix:**
+```bash
+# Run migrations (if available)
+vds-cli db-query --run-migrations
+```
+
+## External API Errors
+
+### `401 Unauthorized: Confluence`
+
+**Cause:** Token invalid or expired.
+
+**Fix:**
+```bash
+# Generate new token in Confluence UI
+# Update ~/.vds/.env
+```
+
+**Prevention:** Set a calendar reminder to rotate tokens every 90 days.
+
+### `Connection timeout: SonarQube`
+
+**Cause:** SonarQube server unreachable.
+
+**Fix:**
+```bash
+# Check connectivity
+curl -I $SONARQUBE_URL
+
+# Verify VPN if required
+```
+
+## Git Errors
+
+### `fatal: not a git repository`
+
+**Cause:** Running git command outside a repo.
+
+**Fix:**
+```bash
+cd /path/to/git/repo
+# or
+vds-cli git worktree-list
+```
+
+### `error: pathspec 'branch-name' did not match`
+
+**Cause:** Branch does not exist.
+
+**Fix:**
+```bash
+# List branches
+git branch -a
+
+# Create branch
+git checkout -b branch-name
+```
+
+## See Also
+
+- [Troubleshooting Guide](../how-to/troubleshooting-guide.md)
+- [Configuration Reference](../reference/configuration-reference.md)

package/skills/vds-skill/runtime/docs/agents/reference/configuration-reference.md

@@ -0,0 +1,128 @@
+<!-- diátaxis: reference -->
+
+# Configuration Reference
+
+All WHO ecosystem configuration lives in `~/.vds/.env`. This file is loaded automatically by `vds-cli` and all orchestrators.
+
+## Quick Template
+
+```bash
+# ~/.vds/.env
+# Copy this template and fill in your values
+
+# === Confluence ===
+CONFLUENCE_INTERNAL_URL=https://confluence.internal.example.com
+CONFLUENCE_EXTERNAL_URL=https://confluence.external.example.com
+INTERNAL_CONFLUENCE_TOKEN=your_internal_token
+EXTERNAL_CONFLUENCE_TOKEN=your_external_token
+CONFLUENCE_USERNAME=your_username
+CONFLUENCE_PASSWORD=your_password
+
+# === Bitbucket ===
+BITBUCKET_TOKEN=your_bitbucket_token
+VDS_BITBUCKET_HTTP_BASE=https://bitbucket.example.com
+
+# === AI Memory ===
+VDS_AI_MEMORY_BASE_URL=http://localhost:8000
+VDS_AI_MEMORY_API_KEY=your_api_key
+
+# === General ===
+VDS_USERNAME=your_username
+VDS_PASSWORD=your_password
+VDS_SKILLS_SYNC_DIR=/path/to/vds-skills
+```
+
+## Environment Variables
+
+### Confluence
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CONFLUENCE_INTERNAL_URL` | Yes | — | Internal Confluence base URL |
+| `CONFLUENCE_EXTERNAL_URL` | Yes | — | External Confluence base URL |
+| `INTERNAL_CONFLUENCE_TOKEN` | Yes* | — | Token for internal Confluence |
+| `EXTERNAL_CONFLUENCE_TOKEN` | Yes* | — | Token for external Confluence |
+| `CONFLUENCE_USERNAME` | Yes* | — | Username for basic auth |
+| `CONFLUENCE_PASSWORD` | Yes* | — | Password for basic auth |
+| `CONFLUENCE_RETRY_BACKOFF` | No | 1.0 | Retry backoff initial (seconds) |
+| `CONFLUENCE_HTTP_TIMEOUT` | No | 30.0 | HTTP read timeout (seconds) |
+
+*Either token-based or username/password auth is required.
+
+### Bitbucket
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BITBUCKET_TOKEN` | Yes | — | Personal access token |
+| `VDS_BITBUCKET_HTTP_BASE` | No | — | Bitbucket server base URL |
+
+### AI Memory
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VDS_AI_MEMORY_BASE_URL` | No | — | Memory service URL |
+| `VDS_AI_MEMORY_API_KEY` | No | — | API key for memory service |
+
+### General
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VDS_USERNAME` | No | — | Default username for services |
+| `VDS_PASSWORD` | No | — | Default password for services |
+| `VDS_SKILLS_SYNC_DIR` | No | — | Path to vds-skills checkout |
+
+## Per-Service Configuration
+
+### Audit Orchestrator
+Uses Confluence and Postgres credentials. No additional env vars required.
+
+### Progress Report Orchestrator
+Uses Postgres and Redis. Connection strings are configured in the orchestrator's config module.
+
+### Telegram Bridge
+Uses the general `VDS_USERNAME`/`VDS_PASSWORD` for authentication with the Telegram bot API. Bot tokens are stored separately in the Telegram configuration.
+
+### Scheduler
+Uses Redis for job queue state. Connection configured in `SCHEDULER_REDIS_URL` (if set) or defaults to `redis://localhost:6379`.
+
+### Embedding (Phase 225+)
+Pluggable embedding providers (Ollama, OpenAI, Cohere, Voyage, Mistral, Jina, local, hash).
+Core prefix: `VDS_AGENT_CORE_EMBED__*`. Per-orchestrator subclasses use custom prefixes (e.g. `VDS_AUDIT_EMBED__*`).
+See [Embedding Architecture](../../vds_agent_core/docs/embedding.md) for full provider reference, dimension constraints, and cloud-failover playbooks.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VDS_AGENT_CORE_EMBED__PROVIDER` | No | `ollama` | Provider name (ollama, openai, cohere, voyage, mistral, jina, local, hash) |
+| `VDS_AGENT_CORE_EMBED__BASE_URL` | No | — | Provider API endpoint (unused for local/hash) |
+| `VDS_AGENT_CORE_EMBED__API_KEY` | No | — | Provider API key (cloud providers only) |
+| `VDS_AGENT_CORE_EMBED__MODEL_STANDARD` | No | `bge-m3` | Embedding model name |
+| `VDS_AGENT_CORE_EMBED__DIMENSION` | No | 1024 | Vector dimension (validated against provider defaults) |
+| `VDS_AGENT_CORE_EMBED__TIMEOUT_SECONDS` | No | 30 | HTTP timeout for provider calls |
+| `VDS_AGENT_CORE_EMBED__VERIFY_DIM_AGAINST_QDRANT` | No | `true` | Validate dimension vs live Qdrant collection |
+
+## Troubleshooting Configuration
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `vds-cli` cannot find orchestrators | `VDS_SKILLS_SYNC_DIR` missing | Set to absolute path of vds-skills checkout |
+| Confluence sync fails with 401 | Token expired | Regenerate token in Confluence user settings |
+| Bitbucket operations fail | `BITBUCKET_TOKEN` missing or invalid | Create token in Bitbucket → Personal Access Tokens |
+| AI Memory not connecting | `VDS_AI_MEMORY_BASE_URL` incorrect | Verify service is running: `curl $VDS_AI_MEMORY_BASE_URL/health` |
+
+## Reloading Configuration
+
+`vds-cli` reads `~/.vds/.env` on each invocation. No restart is required after editing.
+
+```bash
+# Edit the file
+$EDITOR ~/.vds/.env
+
+# Verify it's readable
+vds-cli --help
+```
+
+## See Also
+
+- [Quick Start](../tutorials/quick-start.md)
+- [System Requirements](../reference/system-requirements.md)
+- [Confluence Sync Reference](../reference/confluence-sync.md)

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

@@ -0,0 +1,56 @@
+<!-- diátaxis: reference -->
+
+# Confluence Orchestrator
+
+> Manage Confluence content: create, update, copy pages, upload attachments, and sync doc inventories programmatically.
+
+## Scope
+
+**What this orchestrator does:**
+- Create or update pages under a specific parent (e.g., WHO Documentation Hub).
+- Copy page trees with optional label filtering.
+- Upload local files as page attachments.
+- Generate table-of-contents and navigation pages automatically.
+- Sync markdown docs to Confluence as formatted content.
+
+**What it does NOT do:**
+- Does not manage Confluence space settings or user permissions.
+- Does not provide full HTML rendering (XHTML subset only).
+
+**Primary users:** AI agents syncing doc states; human leads publishing reports.
+
+## CLI Entry
+
+```bash
+vds-cli confluence --help
+vds-cli confluence-cli --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `create-page` | Create a page under a parent | `--space`, `--parent-id`, `--title` |
+| `update-page` | Edit an existing page body | `--page-id`, `--file` |
+| `copy-tree` | Copy a page and its children | `--src-page-id`, `--dst-parent-id` |
+| `upload-attachment` | Attach a file to a page | `--page-id`, `--file-path` |
+| `get-page` | Retrieve page metadata and body | `--page-id` |
+| `search` | Search pages by text | `--query`, `--space` |
+
+## Common Workflows
+
+### Workflow 1: Doc Inventory Sync
+1. Run `vds-cli docs ecosystem-index --generate`.
+2. Push the result to Confluence: `vds-cli confluence create-page --parent-id=57250660 --file=ECOSYSTEM-DOCS.md`.
+3. Verify with `vds-cli confluence search --query="WHO Ecosystem"`.
+
+### Workflow 2: Audit Evidence Attachment
+1. After `vds-cli audit`, locate the `evidence/` directory.
+2. Upload all `.html` files: `vds-cli confluence upload-attachment --page-id=88716821 --file-path=evidence/`.
+3. Update the audit page with evidence links.
+
+## Related
+
+- **Orchestrators:** [jira](jira-orchestrator.md), [bitbucket](bitbucket-orchestrator.md), [progress](progress-orchestrator.md)
+- **Skills:** [confluence-skill](../../../../vds-skills/skills/)
+- **Confluence:** TTCN24/WHO-Project (pageId 57250660)

package/skills/vds-skill/runtime/docs/agents/reference/confluence-sync-target.md

@@ -0,0 +1,111 @@
+<!-- diátaxis: reference -->
+# Confluence Sync Target — WHO-Project Ecosystem Documentation
+
+> **Last synced:** 2026-04-30
+> **Source:** `docs/agents/reference/confluence-sync-target.md` → `vds-cli docs confluence-sync`
+
+This page is the target of the `vds-cli docs confluence-sync` command. Edit this file, then run:
+
+```bash
+vds-cli docs confluence-sync
+```
+
+## Canonical Spec Location (Consolidated 2026-04-29)
+
+Previously scattered across four directories. Now unified in `ARCHIVE/`:
+
+| Old Location | Status |
+|-------------|--------|
+| `.gpt-5.4/specs/ARCHIVE/who-docs-canonical/` | Archived (Phase 177) |
+| `.gpt-5.4/specs/ARCHIVE/who-docs-phase-178/` | Archived (Phase 178) |
+| `.gpt-5.4/specs/ARCHIVE/who-docs-phase-179/` | Archived (Phase 179) |
+| `.gpt-5.4/specs/ARCHIVE/who-project-documentation-enhancement/` | **Canonical (ARCHIVED, completed)** |
+
+### Canonical Spec Triplet
+
+**`.gpt-5.4/specs/ARCHIVE/who-project-documentation-enhancement/`**
+
+| File | Version | Purpose |
+|------|---------|---------|
+| `requirements.md` | **v2.0.1** | Problem statement, scope, acceptance criteria, post-179 merge state |
+| `design.md` | v2.0.0 | Tiered context, Diátaxis, validation, observability |
+| `tasks.md` | **v2.0.1** | Unified DOC-001 to DOC-027 + DOC-019–026 post-179 merge tasks |
+## Latest Acceptance Gates (Phase 179)
+
+| Gate | Before | After |
+|------|--------|-------|
+| **Unit Tests** | 201 | **203 passed** |
+| **Doc Quality Score** | 0.79 | **0.80** |
+| **Low Docs (<0.5)** | 2 | **0** |
+| **Validation Issues** | 3 warnings | **0** |
+| **Freshness Pairs** | 6 | **8** (+ECOSYSTEM files) |
+
+## Recently Added CLI Surfaces
+
+| Command | Purpose |
+|---------|---------|
+| `vds-cli docs onboarding-funnel` | Aggregate tool-use by Diátaxis quadrant |
+| `vds-cli docs freshness-heatmap` | Quant lag days per freshness pair |
+| `vds-cli docs ecosystem-index` | Multi-collector daily ecosystem pulse |
+| `vds-cli docs validate --check-ecosystem` | Warn if ECOSYSTEM-DOCS.md/CHANGELOG.md missing |
+| `vds-cli telegram status` | Telegram bridge daemon status |
+| `vds-cli telegram audit` | Telegram bridge audit log |
+| `vds-cli telegram session` | Claude session store ops |
+| `vds-cli telegram logs` | Bridge/shim log tail |
+| `vds-cli telegram restart` | Hot-reload bridge daemon |
+
+
+## Sync Scope
+
+**English pages** (auto-managed by CI pipeline):
+| Page | ID | Status |
+|------|-----|--------|
+| WHO-Project Ecosystem Documentation | 98997962 | ✅ Auto-synced |
+| Ecosystem Installation Guide | 98997963 | ✅ Auto-synced |
+| vds-scripts Quick Reference | 98997964 | ✅ Auto-synced |
+| vds-skills Quick Reference | 98997965 | ✅ Auto-synced |
+| vds-claude-plugins Quick Reference | 98997966 | ✅ Auto-synced |
+| Documentation Health Dashboard | 98997968 | ✅ Auto-synced |
+
+**Vietnamese pages** (manually managed, IDs mapped in `.confluence.yaml`):
+| Page | ID | Status | Note |
+|------|-----|--------|------|
+| Hướng dẫn cài đặt hệ sinh thái | 99846963 | ⚠️ Manual | Created externally, not in CI scope |
+| Tài liệu tham khảo vds-scripts | 99846964 | ⚠️ Manual | Created externally, not in CI scope |
+| Tài liệu tham khảo vds-skills | 99846965 | ⚠️ Manual | Created externally, not in CI scope |
+| Tài liệu tham khảo vds-claude-plugins | 99846966 | ⚠️ Manual | Created externally, not in CI scope |
+
+> **Note:** Vietnamese pages require manual content updates. The sync pipeline updates English pages only. Page IDs are preserved in `docs/.confluence.yaml` for reference.
+
+## Doc Ecosystem Metrics (vds-scripts)
+
+| Metric | Value |
+|--------|-------|
+| Scored docs | **110** (+26 new) |
+| Average quality | 0.85/1.0 |
+| Low-quality docs | 0 |
+| Orchestrators | **37** in router.py + **37** reference docs |
+| Vietnamese pages | 87 (39 orchestrator + 48 other) |
+| New Phase 180 docs | 16 (+8 vi-VN translations) |
+| Telegram bridge | 102 tests, 9 refs, daemon + 2 runners |
+| Skills | 27 with SKILL.md |
+| Freshness pairs | 18 |
+
+---
+
+## Sync Instructions
+
+**Edit `confluence-sync-target.md`** (this file) to update Confluence. Then push:
+
+```bash
+git add docs/agents/reference/confluence-sync-target.md
+git commit -m "docs: sync target update"
+git push origin HEAD
+```
+
+Then either wait for the CI pipeline or run manually:
+
+```bash
+vds-cli docs confluence-sync --dry-run  # preview
+vds-cli docs confluence-sync             # apply
+```

package/skills/vds-skill/runtime/docs/agents/reference/confluence-sync.md

@@ -0,0 +1,46 @@
+<!-- diátaxis: reference -->
+# `vds-cli docs confluence-sync` — Confluence Documentation Sync
+
+> One-way sync from local Markdown to Confluence pages.
+
+```bash
+vds-cli docs confluence-sync [--repo-root PATH] [--space-key SPACE]
+```
+
+## Synopsis
+
+Pushes selected Markdown docs (e.g., `docs/agents/**/*.md`) to a Confluence space.
+Requires a `confluence_access_token` in the shared env (`~/.vds/shared.env`).
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--repo-root` | `Path` | `CWD` | Repository root carrying docs to sync |
+| `--space-key` | `str` | `WHO` | Confluence space key |
+| `--dry-run` | `bool` | `False` | Preview changes without writing |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All pages updated or no changes |
+| `1` | Auth missing, network failure, or page conflict |
+
+## Prerequisites
+
+1. `confluence_access_token` exported in `~/.vds/shared.env`
+2. Space read/write permission for the bot account
+3. Page IDs cached in `docs/.confluence_ids.json` (auto-created on first run)
+
+## Caveats
+
+- **Rate limits**: 1 req/s enforced internally; burst may trigger 429
+- **Images**: Relative image paths are resolved against `repo_root`; unsupported formats are skipped with a warning
+- **Parent page**: The first H1 becomes the page title; H2/H3 become Confluence headings
+- **Tables**: Standard Markdown tables work; merged cells are flattened
+
+## See Also
+
+- [CLI Commands Reference](./cli-commands.md)
+- [Confluence Orchestrator Reference](./confluence-orchestrator.md)

package/skills/vds-skill/runtime/docs/agents/reference/db-query-orchestrator.md

@@ -0,0 +1,93 @@
+<!-- diátaxis: reference -->
+
+# DB Query Orchestrator
+
+> Execute safe read-only SQL queries across Postgres, SQL Server, and MariaDB connections.
+
+## Scope
+
+- **Does:** Run validated read-only SQL, list configured connections, test connectivity, and export results as JSON or TSV.
+- **Does NOT:** Execute write operations (INSERT, UPDATE, DELETE, DDL). Does not replace pgAdmin or database IDEs.
+- **Primary users:** AI agents (data retrieval), operators (ad-hoc queries), CI pipelines (read-only assertions).
+
+## CLI Entry
+
+```bash
+# Via unified router
+vds-cli db-query --help
+
+# Direct entry
+vds-cli db-query --help
+```
+
+## Key Commands
+
+| Command | Purpose | Common Flags |
+|---------|---------|-------------|
+| `--list-connections` | Discover configured connection aliases from env | `--env` |
+| `--test` | Probe a single connection (SELECT 1) | `--conn` |
+| `--query` | Execute a read-only SQL query | `--conn`, `--format` |
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--conn <dbtype>:<alias>` | Connection id (e.g., `postgres:analytics`) |
+| `--query "SQL"` | Read-only SQL to execute |
+| `--format json|tsv` | Output format (default: json) |
+| `--env <path>` | Path to `.env` with `VDS_DB_*` definitions |
+| `--test` | Run connectivity probe on `--conn` |
+| `--list-connections` | List all discovered connections |
+| `--json-only`, `-j` | Output clean JSON only |
+| `--quiet`, `-q` | Suppress non-essential output |
+
+## Connection Configuration
+
+Connections are discovered from environment variables using the pattern:
+```bash
+VDS_DB_POSTGRES_ANALYTICS_URL=jdbc:postgresql://host:5432/dbname
+VDS_DB_POSTGRES_ANALYTICS_USER=reader
+VDS_DB_POSTGRES_ANALYTICS_PASSWORD=***
+```
+
+Or explicitly via `VDS_DB_CONNECTIONS=postgres:analytics,sqlserver:warehouse`.
+
+Supported types: `postgres`, `sqlserver`, `mariadb` (aliases: `postgresql`, `mssql`, `mysql`).
+
+## Query Safety
+
+Only queries starting with `SELECT`, `WITH`, `EXPLAIN`, `SHOW`, or `DESCRIBE` are permitted. Write prefixes (INSERT, UPDATE, DELETE, ALTER, DROP, TRUNCATE, CREATE, MERGE, GRANT, REVOKE) are rejected before execution.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage error (unsupported format, missing flags) |
+| 3 | Config error (missing env, unknown connection) |
+| 4 | Validation error (write query blocked) |
+| 5 | General runtime error |
+
+## Workflow Examples
+
+```bash
+# List all configured connections
+vds-cli db-query --list-connections
+
+# Test connectivity to a specific connection
+vds-cli db-query --conn postgres:analytics --test
+
+# Run a read-only query and get JSON results
+vds-cli db-query --conn postgres:analytics --query "SELECT COUNT(*) FROM audit_runs"
+
+# Export results as TSV for spreadsheet import
+vds-cli db-query --conn sqlserver:warehouse --query "SELECT TOP 10 * FROM logs" --format tsv
+
+# Use a custom env file
+vds-cli db-query --env ~/.vds/prod.env --conn mariadb:legacy --query "SHOW TABLES" --json-only
+```
+
+## Related
+
+- **Orchestrators:** [grafana](grafana-orchestrator.md), [elastic](elastic-orchestrator.md), [metabase](metabase-orchestrator.md)
+- **Skills:** [memory-orchestrator-skill](../../../../vds-skills/skills/memory-orchestrator-skill/SKILL.md)