@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/agents/how-to/first-audit-run.md

@@ -1,83 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# First Audit Run
-
-> Step-by-step guide for running your first repository audit using the WHO-project toolchain.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes
-- Target repo(s) accessible via Bitbucket
-
-## Quick Start
-
-### 1. Discover available audit skills
-
-```bash
-cat WHO-project/vds-skills/skills/ | grep audit
-```
-
-Expected output includes `audit-orchestrator-skill`.
-
-### 2. Load the audit skill
-
-```bash
-cat WHO-project/vds-skills/skills/audit-orchestrator-skill
-```
-
-This prints the skill's operational contract, CLI flags, and examples.
-
-### 3. Run a single-repo audit
-
-```bash
-vds-cli audit run --repo vds-scripts --scope quick
-```
-
-- `--repo`: target repository slug
-- `--scope quick`: fast pass (rules + structure, no deep analysis)
-- `--scope full`: comprehensive audit (slower, more thorough)
-
-### 4. Review results
-
-Output is written to `audits/<timestamp>-<repo>-<scope>.md`.
-
-```bash
-cat audits/$(ls -t audits/ | head -n 1)
-```
-
-### 5. Escalate findings
-
-If the audit surfaces issues:
-
-```bash
-# Auto-create tickets from findings
-vds-cli audit escalate --from audits/<file>.md --tracker jira
-
-# Or export as Confluence table
-vds-cli audit export --format confluence --from audits/<file>.md
-```
-
-## Common Flags
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Show what would be audited without running |
-| `--rules-only` | Skip code analysis, check rules compliance only |
-| `--output-dir` | Custom output directory (default: `audits/`) |
-| `--format json` | Machine-readable output instead of markdown |
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `audit-orchestrator-skill not found` | Run `vds-cli skills sync --agent claude` to refresh catalog |
-| `Permission denied` on Bitbucket | Check `INTERNAL_BITBUCKET_TOKEN` in `~/.vds/.env` |
-| Empty audit output | Verify `--repo` slug matches Bitbucket exactly |
-| Slow execution | Use `--scope quick` or `--rules-only` for faster feedback |
-
-## Next Steps
-
-- Read the full audit skill: `cat WHO-project/vds-skills/skills/audit-orchestrator-skill`
-- Review the audit triage playbook: `docs/agents/reference/audit-triage-playbook.md`
-- Run cross-repo audits: `vds-cli audit run --repo-list repos.txt --scope full`

package/skills/vds-skill/vds-scripts/docs/agents/how-to/index.md

@@ -1,49 +0,0 @@
-<!-- diátaxis: how-to -->
-# How-To Guides
-
-> Step-by-step workflow guides for common VDS operations.
-
-## Workflow Quick Reference
-
-Use the following command to list all how-to guides in a script or orchestrator context:
-
-```bash
-vds-cli docs index --agent-script-path docs/agents/how-to/ --check-diataxis
-```
-
-## Available Guides
-
-| Guide | Orchestrator | Skill |
-|-------|-------------|-------|
-| [Install and Bootstrap WHO Scripts and Skills](install-and-bootstrap-who-scripts-and-skills.md) | `vds-scripts` | bootstrap |
-| [Configure Agents](configure-agents.md) | `vds-scripts` | config |
-| [Run Ecosystem Daily Report](run-ecosystem-daily-report.md) | `scheduler_orchestrator` | reporting |
-| [Apply Phase 3 Migration](apply-phase3-migration.md) | `scheduler_orchestrator` | migration |
-
-## Writing a New How-To
-
-1. Copy `TEMPLATE.md` (if available) or an existing guide.
-2. Add the `<!-- diátaxis: how-to -->` header.
-3. Include the prerequisite section, step-by-step workflow, and error handling.
-4. Run the doc quality gate before committing:
-
-```bash
-vds-cli docs validate --check-diataxis --repo-root .
-```
-
-## Workflow
-
-```mermaid
-graph LR
-    A[Identify Task] --> B[Match How-To]
-    B --> C[Follow Steps]
-    C --> D[Run Quality Gate]
-    D --> E[Commit]
-```
-
-## See Also
-
-- [Tutorials](../tutorials/) — Learning-oriented walkthroughs for new team members
-- [Reference](../reference/) — API contracts, CLI commands, and orchestrator runbooks
-- [Explanation](../explanation/) — Architectural decisions and design rationale
-- [Skills overview](choosing-the-right-skill.md) — How to pick the correct skill for a task

package/skills/vds-skill/vds-scripts/docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md

@@ -1,314 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Install And Bootstrap WHO Scripts And Skills
-
-Use this guide when you need a clean, explicit setup path for the WHO scripts workspace and the WHO skills catalog.
-It is written for both human contributors and AI agents.
-
-## 1. Choose the right working mode
-
-- **Dedicated `vds-scripts` worktree**: prefer `./scripts/worktree_uv.sh ...` for all `uv` commands.
-- **Main `vds-scripts` checkout**: `uv sync` and `uv run --project ...` are acceptable.
-- **External clone**: set explicit `VDS_SCRIPTS_PATH` / `VDS_SKILLS_PATH` values and do not assume monorepo-relative defaults.
-
-## 2. Install prerequisites
-
-### Required for scripts workspace
-
-- `git`
-- `uv`
-- a supported shell environment
-
-Install `uv`:
-
-- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
-- or use the package-manager workflow approved in your environment
-
-### Optional but recommended for skill workflows
-
-- `python3` (or `python`) for running `vds-skills-sync`
-
-This is required when you want `vds-skills-sync` to generate `AGENTS.md` from
-`registry.yaml`. It is not required when you only need to read canonical skill
-files directly.
-
-## 3. Set canonical paths
-
-Add these to `VDS_ENV_FILE` or `<config-root>/.env` for persistence when appropriate.
-`<config-root>` resolves from `VDS_CONFIG_DIR` when set, otherwise from the user-home VDS default.
-
-```bash
-export VDS_SCRIPTS_PATH="${VDS_SCRIPTS_PATH:-./WHO-project/vds-scripts}"
-export VDS_SKILLS_PATH="${VDS_SKILLS_PATH:-./WHO-project/vds-skills/skills}"
-```
-
-## 4. Bootstrap the scripts workspace
-
-### Dedicated `vds-scripts` worktree
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-./scripts/worktree_uv.sh sync --all-packages
-```
-
-### Non-worktree checkout
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-uv sync --all-packages
-```
-
-## 5. Verify the scripts workspace
-
-Run the minimum verification set before deeper work:
-
-```bash
-cd "$VDS_SCRIPTS_PATH"
-./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli audit --help
-./scripts/worktree_uv.sh run --project vds_cli vds-cli spec --help
-```
-
-If you are not in a dedicated worktree, use `uv run --project ...` equivalents.
-
-If `vds-cli env status` reports missing credentials, configure `~/.vds/.env` per §11 below before continuing. The same section covers the canonical git credential helper (`vds-cli env install-git-helper`).
-
-## 6. Verify the skills catalog
-
-```bash
-ls -la "$VDS_SKILLS_PATH/"
-```
-
-Canonical maintained skills live under:
-
-- `WHO-project/vds-skills/skills/`
-
-Do not treat `.agent/skills/` as an independent authoring source.
-
-## 7. Human workflow: OpenSkills usage
-
-When `node`/`npx` is available and OpenSkills is configured for the workspace:
-
-```bash
-ls WHO-project/vds-skills/skills/
-cat WHO-project/vds-skills/skills/vds-scripts-skill
-cat WHO-project/vds-skills/skills/audit-orchestrator-skill
-```
-
-Use OpenSkills when you want the standard install/read/sync workflow.
-
-## 8. AI-agent workflow: direct fallback when OpenSkills is unavailable
-
-If `cat WHO-project/vds-skills/skills/<skill-name>` fails because the current shell context does not resolve the workspace skill configuration correctly, fall back to the canonical skill files directly.
-
-Read from:
-
-- `WHO-project/vds-skills/skills/<skill-name>/SKILL.md`
-
-Examples:
-
-- `WHO-project/vds-skills/skills/vds-scripts-skill/SKILL.md`
-- `WHO-project/vds-skills/skills/audit-orchestrator-skill/SKILL.md`
-- `WHO-project/vds-skills/skills/spec-creation-skill/SKILL.md`
-
-This fallback is valid because the canonical source of truth is the WHO skills repository, not the mirror/symlink surfaces.
-
-## 9. Minimum agent-readiness checklist
-
-Before an AI agent proceeds, confirm:
-
-- `VDS_SCRIPTS_PATH` points to the intended scripts workspace
-- `VDS_SKILLS_PATH` points to the canonical skills directory
-- routed help works: `vds-cli --help`
-- specialist help works: `vds-audit --help`, `vds-cli spec --help`
-- evolution loop works: `.venv/bin/vds-cli evolution status` (or `vds-cli evolution status`)
-- the agent knows whether it is using OpenSkills loading or direct canonical skill-file reads
-- `.agent/skills/` is treated as compatibility-only, not as the maintained source
-
-## 10. OpenSpace evolution loop runtime (when using `vds_evolution`)
-
-If you intend to use the WHO ecosystem evolution loop with a real OpenSpace runtime,
-prefer repo-local runtime paths under the scripts workspace and keep durable env
-configuration in the shared VDS env layer.
-
-Recommended durable env placement:
-- `VDS_ENV_FILE`
-- or the default shared env file: `~/.vds/.env`
-
-Recommended variables:
-
-```bash
-OPENSPACE_WORKSPACE="$VDS_SCRIPTS_PATH/.openspace"
-OPENSPACE_HOST_SKILL_DIRS="$VDS_SCRIPTS_PATH/.openspace/shadow/skills"
-OPENSPACE_TRANSPORT=stdio
-OPENSPACE_AUTONOMOUS_ENABLED=false
-```
-
-Notes:
-- Keep autonomy disabled until the OpenSpace runtime is verified healthy.
-- Prefer repo-local `.openspace/` over ad hoc host-only directories so the setup is part of the workspace.
-- Refresh the shadow skill mirror from the canonical skills catalog before enabling automated evolution.
-- Ensure `openspace-mcp` is installed and callable in the active shell before relying on stdio transport.
-- Treat the official HKUDS/OpenSpace repository as the reference for runtime startup and env semantics; prefer the officially documented `stdio` and `sse` transports for real setup.
-
-### vds-cli evolution script execution
-
-The `vds-cli evolution` script works from any CWD due to a spec_from_file_location workaround that bypasses the openspace `__path_hook__` issue in mixed venv environments.
-
-**Available entry points:**
-
-| Entry | Location | Usage |
-|-------|----------|-------|
-| Standalone | `.venv/bin/vds-cli evolution` | Direct execution from scripts repo |
-| Tracked shell | `vds-cli evolution-mono.sh` | For monorepo compatibility |
-| Via router | `vds-cli evolution ...` | Through the unified CLI |
-
-**Typical commands:**
-
-```bash
-# Standalone (works from any CWD)
-.venv/bin/vds-cli evolution status
-.venv/bin/vds-cli evolution list
-
-# Via router
-vds-cli evolution status
-vds-cli evolution list
-
-# OpenSpace bootstrap
-vds-cli evolution openspace-bootstrap
-vds-cli evolution openspace-doctor
-```
-
-**Root cause note:** When the monorepo `.venv` contains both `openspace` and `vds-cli evolution` packages installed via `uv pip install -e`, the openspace editable installer registers a custom `PathEntryFinder` in `sys.path_hooks`. This causes `importlib.util.find_spec()` to return `None` for `vds-cli evolution` from certain CWDs. The script workaround uses `spec_from_file_location` + `module_from_spec` to bypass the hook entirely and directly load from known file paths.
-
-## 11. Configure credentials in `~/.vds/.env`
-
-This section defines the canonical shape of `~/.vds/.env` per `who-ecosystem-alignment` Phase 5 FR-18..FR-25. The file is the single source of credentials for all VDS orchestrators. Values shown below are placeholders — replace them with your real credentials. NEVER commit real credential values anywhere (NFR-12).
-
-### 11.1 Required keys (Atlassian shared identity)
-
-The three Atlassian orchestrators (`bitbucket_orchestrator`, `confluence_orchestrator`, `jira_orchestrator`) share the corporate SSO identity per FR-18 (Atlassian shared-identity model). Both keys are mandatory:
-
-```dotenv
-VDS_USERNAME=<your-corporate-username>
-VDS_PASSWORD=<your-corporate-password>
-```
-
-Removing either key simultaneously breaks Bitbucket SDK, Confluence SDK, and JIRA SDK access — see the Credential Consumer Inventory in `.gpt-5.4/specs/who-ecosystem-alignment/design.md` Phase 5 §Credential Consumer Inventory.
-
-### 11.2 Optional per-product tokens (token-preference asymmetry)
-
-Per FR-19, each Atlassian product accepts an additional per-product token. The resolution order is **asymmetric by product**:
-
-| Orchestrator | Token env var | Resolution priority |
-|---|---|---|
-| `bitbucket_orchestrator` | `BITBUCKET_TOKEN` | **Token preferred** over basic auth when both present |
-| `jira_orchestrator` | `JIRA_TOKEN` | **Token preferred** over basic auth when both present |
-| `confluence_orchestrator` | `INTERNAL_CONFLUENCE_TOKEN`, `EXTERNAL_CONFLUENCE_TOKEN` | **Basic auth primary** per `.claude/rules/sdk-and-auth-rules.md`; tokens are fallback |
-
-Configure tokens only if you've been issued one:
-
-```dotenv
-BITBUCKET_TOKEN=<your-bbdc-pat>
-JIRA_TOKEN=<your-jira-pat>
-INTERNAL_CONFLUENCE_TOKEN=<your-internal-confluence-token>
-EXTERNAL_CONFLUENCE_TOKEN=<your-external-confluence-token>
-```
-
-A token set to an empty string or whitespace is treated as absent per AC-19.5 — the SDK and the git credential helper both fall back to basic auth.
-
-### 11.3 Isolated-prefix orchestrators (non-Atlassian)
-
-Per FR-18 AC-18.2, non-Atlassian orchestrators use isolated credential prefixes and MUST NOT bind `VDS_PASSWORD`:
-
-```dotenv
-# Grafana
-VDS_GRAFANA_USER=<your-grafana-user>
-VDS_GRAFANA_PASSWORD=<your-grafana-password>
-VDS_GRAFANA_TOKEN=<your-grafana-pat>          # optional; preferred when set
-
-# SonarQube
-VDS_SONAR_USER=<your-sonar-user>
-VDS_SONAR_PASSWORD=<your-sonar-password>
-VDS_SONAR_TOKEN=<your-sonar-pat>              # optional; preferred when set
-
-# Elasticsearch (basic only — no token alternative in current SDK)
-VDS_ELASTIC_USER=<your-elastic-user>
-VDS_ELASTIC_PASSWORD=<your-elastic-password>
-```
-
-These prefixes can be rotated independently of the Atlassian shared identity.
-
-### 11.4 Endpoint URLs
-
-Per-orchestrator endpoint URLs are environment-specific:
-
-```dotenv
-VDS_BITBUCKET_URL=<your-bitbucket-base-url>
-VDS_CONFLUENCE_URL=<your-confluence-base-url>
-VDS_GRAFANA_URL=<your-grafana-url>
-# ... add one per orchestrator you intend to use
-```
-
-### 11.5 Install the git credential helper (`vds-cli env install-git-helper`)
-
-Per FR-23 (helper lifecycle via vds-cli) + FR-24 (single canonical artifact), the operator git credential helper is installed and managed exclusively via `vds-cli env`. NEVER install or upgrade the helper by manual `cp` / `chmod` / `git config` (FR-23 AC-23.1).
-
-```bash
-# Install the canonical helper at $HOME/.vds/bin/git-credential-vds (mode 0o700)
-# and configure git credential.helper to use it. Removes any pre-FR-24 artifacts
-# (signature-checked per AC-24.6 — user-authored files are preserved with a warning).
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env install-git-helper
-
-# Verify install state (exit 0 ⇔ all checks pass)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper
-
-# If a Bitbucket account-lock cooldown is active, reset after fixing creds:
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper --reset-cooldown
-
-# Uninstall (idempotent — safe to call when nothing is installed)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env remove-git-helper
-
-# Uninstall + delete cooldown state file
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env remove-git-helper --purge
-```
-
-The helper enforces three contracts:
-
-- **Host allowlist** (FR-20 AC-20.1): credentials emitted ONLY for `bitbucket.digital.vn`. Extensible via `VDS_BITBUCKET_HOSTS` in `~/.vds/.env` (comma-separated). Never readable from shell env per AC-20.6 — extension requires `~/.vds/.env` edit. Other git hosts get silent fall-through to the next configured helper (e.g., osxkeychain).
-- **Lockout prevention** (FR-21): 3 failed-auth events within 60 seconds trigger a 300-second silent cooldown. State file at `$HOME/.vds/.git-credential-helper-cooldown.json` (mode `0o600` per AC-21.7). Reset via `verify-git-helper --reset-cooldown`.
-- **Token preference** (mirrors FR-19 for Bitbucket per AC-20.3): emits `BITBUCKET_TOKEN` over `VDS_PASSWORD` when both are configured.
-
-### 11.6 Verification
-
-Confirm the full credential + helper stack:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
-./scripts/worktree_uv.sh run --project vds_cli vds-cli env verify-git-helper
-./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
-```
-
-`vds-cli doctor` includes a "Git credential helper" status row (`installed` / `missing` / `broken`) per FR-23 AC-23.5, with a remediation hint pointing to `vds-cli env install-git-helper`.
-
-### 11.7 Canonical credential model
-
-The full credential resolution invariants — which orchestrators share `VDS_PASSWORD`, why the per-product token preference is asymmetric (Bitbucket/JIRA prefer token; Confluence keeps basic primary), what the helper lifecycle contract is, what file modes are required — live in:
-
-**Canonical credential model: `who-ecosystem-alignment` Phase 5 FR-18..FR-25** at `.gpt-5.4/specs/who-ecosystem-alignment/`.
-
-Refer to that spec when:
-
-- Adding a new orchestrator → declare its credential model (Atlassian-shared vs isolated-prefix) per AC-18.3 and update `design.md` Phase 5 §Credential Consumer Inventory.
-- Proposing changes to `~/.vds/.env` shape → audit which orchestrators read each key.
-- Modifying the git credential helper → AC-25.4 requires paired updates if `BitbucketSettings.get_auth_kwargs` or `vds_cli_common.env._parse_env_file` change.
-
-## 12. Related references
-
-- `../reference/portable-paths-and-config.md`
-- `../reference/cli-help-matrix.md`
-- `../tutorials/who-skills-and-scripts-onboarding.md`
-- `choose-the-right-command-or-skill.md`
-- `.gpt-5.4/specs/who-ecosystem-evolution-loop/`
-- `.gpt-5.4/specs/who-ecosystem-alignment/` (canonical credential model — Phase 5 FR-18..FR-25)

package/skills/vds-skill/vds-scripts/docs/agents/how-to/orchestrator-workflows/analytics-pipeline-workflow.md

@@ -1,165 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Elasticsearch → Grafana → Metabase Analytics Pipeline
-
-> Combine the Elastic, Grafana, and Metabase orchestrators to query logs, build visualizations, and deliver analytics dashboards.
-
-## Prerequisites
-
-- `vds-scripts` cloned and bootstrapped (`./scripts/worktree_uv.sh sync`)
-- `vds-cli doctor` passes with Elastic, Grafana, and Metabase profiles green
-- `~/.vds/.env` contains `ELASTIC_HOST`, `GRAFANA_HOST`, `METABASE_HOST`, and corresponding credentials
-- Index patterns created in Elasticsearch (e.g., `vds-logs-*`)
-
-## Workflow Overview
-
-```
-Elastic (query logs/export data)
-    ↓
-Grafana (visualize metrics)
-    ↓
-Metabase (deliver dashboards)
-```
-
-## Step 1: Query Logs in Elasticsearch
-
-Run a targeted log search to extract raw analytics data.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli elastic search --index "vds-logs-*" \
-  --query '{"bool":{"filter":[{"range":{"@timestamp":{"gte":"now-7d"}}},{"term":{"level":"ERROR"}}]}}' \
-  --size 5000 --output /tmp/elastic-errors.json
-```
-
-Expected output:
-
-```
-[elastic] Index: vds-logs-*
-[elastic] Hits: 3,421
-[elastic] Output: /tmp/elastic-errors.json
-[elastic] Duration: 1.2s
-```
-
-Aggregate errors by service for downstream visualization:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli elastic aggregate --index "vds-logs-*" \
-  --field "service.name" --metric "count" \
-  --time-range "now-7d" --output /tmp/error-agg.json
-```
-
-Expected output:
-
-```
-[elastic] Buckets: 12
-[elastic] Top: audit-orchestrator (847)
-[elastic] Output: /tmp/error-agg.json
-```
-
-## Step 2: Build Grafana Visualizations
-
-Import the aggregated data into a Grafana datasource and create a panel.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana datasource test --name "vds-elastic"
-```
-
-Expected output:
-
-```
-[grafana] Datasource "vds-cli elastic" status: OK
-[grafana] Version: 10.4.1
-```
-
-Create a dashboard with a time-series panel from the Elastic query:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana dashboard create --title "VDS Error Analytics" \
-  --datasource "vds-cli elastic" --panel-type timeseries \
-  --query '{"index":"vds-logs-*","body":{"aggs":{"services":{"terms":{"field":"service.name"}}}}}' \
-  --folder "VDS Operations"
-```
-
-Expected output:
-
-```
-[grafana] Dashboard created: /d/vds-error-analytics
-[grafana] UID: vds-error-analytics
-[grafana] Folder: VDS Operations
-```
-
-Generate a snapshot link for sharing:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli grafana snapshot create --dashboard "vds-error-analytics" \
-  --name "Error Analytics Snapshot $(date +%Y-%m-%d)"
-```
-
-Expected output:
-
-```
-[grafana] Snapshot created: https://grafana.example.com/dashboard/snapshot/vds-error-analytics-2026-04-22
-```
-
-## Step 3: Export Analytics to Metabase
-
-Sync the aggregated dataset to Metabase for self-service exploration.
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase card create --database "vds-analytics" \
-  --name "Weekly Error Distribution" --query-file /tmp/error-agg.json
-```
-
-Expected output:
-
-```
-[metabase] Card created: 2143
-[metabase] Database: vds-analytics
-[metabase] Visualization: table
-```
-
-Add the card to a Metabase dashboard:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase dashboard add-card --dashboard "VDS Operational Metrics" \
-  --card 2143 --col 0 --row 0
-```
-
-Expected output:
-
-```
-[metabase] Dashboard updated: VDS Operational Metrics
-[metabase] Cards: 8
-```
-
-Publish the dashboard for public or embedding access:
-
-```bash
-./scripts/worktree_uv.sh run --project vds_cli \
-  vds-cli metabase dashboard publish --dashboard "VDS Operational Metrics" \
-  --enable-public-link
-```
-
-Expected output:
-
-```
-[metabase] Public link enabled
-[metabase] URL: https://metabase.example.com/public/dashboard/vds-operational-metrics
-```
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `elastic search` returns zero hits | Index pattern mismatch or timestamp field name | Verify index with `vds-cli elastic indices list` |
-| `grafana datasource test` fails | Credentials missing or network egress blocked | Check `GRAFANA_API_KEY` in `~/.vds/.env` |
-| `grafana dashboard create` panel empty | Query JSON malformed | Validate query with `vds-cli elastic search --dry-run` first |
-| `metabase card create` fails | Database connection or schema mismatch | Check `vds-cli metabase database sync --db "vds-analytics"` |
-| Dashboard links return 404 | UID or slug changed after rename | Re-run `vds-cli grafana dashboard list --search "VDS"` |