@ngocsangairvds/vsaf 4.1.9 → 4.1.11

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

@@ -0,0 +1,83 @@
+<!-- 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/runtime/docs/agents/how-to/index.md

@@ -0,0 +1,49 @@
+<!-- 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/runtime/docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md

@@ -0,0 +1,314 @@
+<!-- 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/runtime/docs/agents/how-to/orchestrator-workflows/analytics-pipeline-workflow.md

@@ -0,0 +1,165 @@
+<!-- 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"` |