@ngocsangairvds/vsaf 3.2.15 → 4.0.0

package/tools/vds-scripts/docs/agents/reference/cli-help-matrix.md

@@ -1,84 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/common-errors.md

@@ -1,126 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/configuration-reference.md

@@ -1,128 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/confluence-orchestrator.md

@@ -1,56 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/confluence-sync-target.md

@@ -1,111 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/confluence-sync.md

@@ -1,46 +0,0 @@
-<!-- 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/tools/vds-scripts/docs/agents/reference/db-query-orchestrator.md

@@ -1,93 +0,0 @@
-<!-- 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)