@ngocsangairvds/vsaf 4.1.8 → 4.1.9

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

@@ -1,51 +0,0 @@
-<!-- diátaxis: reference -->
-
-# LSP Orchestrator
-
-> Language Server Protocol operations for code intelligence.
-
-## Scope
-
-- **Does:** Manage LSP servers, query symbols, navigate to definitions, and get hover information.
-- **Does NOT:** Replace IDE features, manage server lifecycles beyond VDS scope, or handle LSP extensions.
-- **Primary users:** AI agents (code analysis), developers (navigation), tooling teams.
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli lsp --help
-
-# Direct entry
-vds-cli lsp --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `symbol` | Query workspace symbols | `--query` |
-| `navigate` | Navigate to definition | `--file`, `--line`, `--column` |
-| `hover` | Get hover information | `--file`, `--line`, `--column` |
-| `server` | Manage LSP server | `--action`, `--language` |
-
-## Common Workflows
-
-### Workflow: Find Symbol Definition
-
-1. Run `vds-cli lsp symbol --query "MyClass"`
-2. Get file/line/column from results
-3. Navigate: `vds-cli lsp navigate --file path.py --line 10 --column 5`
-
-## Related
-
-- **Orchestrators:** [intellij](intellij-orchestrator.md), [code-review](code-review-graph-skill.md), [structure](structure-orchestrator.md)
-- **Confluence:** [WHO LSP](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -1,53 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Markdown Orchestrator
-
-> Markdown formatting and validation for VDS documentation.
-
-## Scope
-
-- **Does:** Format markdown files with consistent wrapping, validate markdown syntax, and check staged or specified files for formatting compliance.
-- **Does NOT:** Render markdown to HTML or validate link targets (use [links-orchestrator](links-orchestrator.md) for that).
-- **Primary users:** AI agents (doc hygiene), developers (pre-commit checks).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli markdown --help
-
-# Direct entry
-vds-cli markdown --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `check` | Check markdown formatting; exit non-zero if changes needed | `--staged`, `--wrap` |
-| `format` | Format markdown files in place | `--staged`, `--wrap` |
-| `version` | Show orchestrator version | — |
-
-## Workflow Examples
-
-```bash
-# Check all tracked markdown files
-vds-cli markdown check
-
-# Check specific files
-vds-cli markdown check docs/*.md README.md
-
-# Check staged files only
-vds-cli markdown check --staged
-
-# Format with custom wrap width
-vds-cli markdown format --wrap 100
-
-# Format staged files
-vds-cli markdown format --staged
-```
-
-## Related
-
-- **Orchestrators:** [links](links-orchestrator.md), [pdf](pdf-orchestrator.md)
-- **Confluence:** [WHO Markdown](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)

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

@@ -1,88 +0,0 @@
-<!-- diátaxis: reference -->
-
-# MCP Orchestrator
-
-> MCP (Model Context Protocol) stdio server exposing VDS platform tools to AI agents.
-
-## Scope
-
-- **Does:** Run a FastMCP stdio server that registers Jira, Confluence, Bitbucket, and Git tools callable by MCP clients.
-- **Does NOT:** Replace direct `vds-cli` usage, manage LLM provider authentication, or expose arbitrary shell execution.
-- **Primary users:** AI agents (tool dispatch via MCP), IDE integrations (Claude Desktop, Cursor), developers (MCP plumbing).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli mcp --help
-
-# Direct entry
-vds-cli mcp-server --help
-```
-
-## Server Behavior
-
-The server starts over stdio transport by default. It loads shared VDS environment configuration on startup and exposes the following tool categories:
-
-| Tool Category | Tools |
-|---------------|-------|
-| Jira | `jira_search`, `jira_get_issue` |
-| Confluence | `confluence_search` |
-| Bitbucket | `bitbucket_list_projects`, `bitbucket_list_repositories` |
-| Git | `git_clone`, `git_status` |
-
-Each tool delegates to `vds-cli` via subprocess and returns stdout/stderr/returncode.
-
-## Tool Examples
-
-```json
-// jira_search
-{"query": "project = NTTC AND status = Open", "limit": 20}
-
-// confluence_search
-{"query": "space = TDOV", "server": "internal", "limit": 10}
-
-// bitbucket_list_repositories
-{"project_key": "LEP"}
-
-// git_clone
-{"project": "lep"}
-```
-
-## Configuration
-
-Requires shared VDS environment (`~/.vds/.env`) with:
-- `VDS_JIRA_*` credentials for Jira tools
-- `VDS_CONFLUENCE_*` credentials for Confluence tools
-- `VDS_BITBUCKET_*` credentials for Bitbucket tools
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Server started successfully |
-| 1 | Configuration or runtime error |
-
-## Workflow Examples
-
-```bash
-# Start the MCP server (stdio transport)
-vds-cli mcp-server
-
-# Start via unified router
-vds-cli mcp
-
-# Configure in Claude Desktop (example)
-# {
-#   "mcpServers": {
-#     "vds": {
-#       "command": "vds-cli mcp-server"
-#     }
-#   }
-# }
-```
-
-## Related
-
-- **Orchestrators:** [jira](jira-orchestrator.md), [confluence](confluence-orchestrator.md), [bitbucket](bitbucket-orchestrator.md)
-- **Skills:** [research-skill](../../../../vds-skills/skills/research-skill/SKILL.md)

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

@@ -1,53 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Memory Orchestrator
-
-> Search, store, and recall cross-session knowledge and observations.
-
-## Scope
-
-- **Does:** Semantic search across memory store, store new observations, recall prior decisions.
-- **Does NOT:** Replace git history, store large binary artifacts.
-- **Primary users:** AI agents (context retrieval), human operators (decision archaeology).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli memory --help
-
-# Direct entry
-vds-cli memory --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `search` | Semantic search | `--limit`, `--tool` |
-| `store` | Store observation | `--tag`, `--priority` |
-| `recall` | Recall by ID or tag | `--id` |
-| `health` | Check memory store health | — |
-
-## Common Workflows
-
-### Workflow: Research with Memory Recall
-
-1. Search prior work: `vds-cli memory search "MCP protocol" --limit 5`
-2. Review stored observations
-3. Store new findings: `vds-cli memory store --tag "mcp-research-2026"`
-4. Cross-reference with current task
-
-## Related
-
-- **Orchestrators:** [research](research-orchestrator.md), [audit](audit-triage-playbook.md)
-- **Skills:** [memory-orchestrator-skill](../../../../vds-skills/skills/memory-orchestrator-skill/SKILL.md)
-- **Confluence:** [WHO Memory](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -1,51 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Metabase Orchestrator
-
-> Metabase analytics and dashboard operations — query questions, export results, inspect collections.
-
-## Scope
-
-- **Does:** Query Metabase questions, export results, inspect collections, and manage dashboard subscriptions.
-- **Does NOT:** Build new dashboards, replace Metabase UI, or manage permissions.
-- **Primary users:** AI agents (data retrieval), analysts, product managers.
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli metabase --help
-
-# Direct entry
-vds-cli metabase --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `query` | Run Metabase question | `--question-id`, `--format` |
-| `export` | Export question results | `--question-id`, `--output` |
-| `collection` | List collection contents | `--collection-id` |
-| `subscribe` | Manage dashboard subscriptions | `--dashboard-id`, `--action` |
-
-## Common Workflows
-
-### Workflow: Export Weekly Metrics
-
-1. Run `vds-cli metabase query --question-id 123 --format csv`
-2. Save output: `--output weekly-metrics.csv`
-3. Share with stakeholders
-
-## Related
-
-- **Orchestrators:** [grafana](grafana-orchestrator.md), [elastic](elastic-orchestrator.md), [db-query](db-query-orchestrator.md)
-- **Confluence:** [WHO Metabase](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -1,71 +0,0 @@
-<!-- diátaxis: reference -->
-# Migration Playbook
-
-Canonical migration commands for each orchestrator. All use the standard Compose
-merge pattern from ADR-INF-10 v2.15.10:
-
-```bash
-docker compose -p vds-platform \
-               -f docker/docker-compose.infra.yml \
-               -f docker/docker-compose.services.yml \
-               -f docker/docker-compose.cli.yml \
-               --profile <profile> \
-               run --rm --no-deps ...
-```
-
-## Auto-Migrate Entrypoints
-
-| Service | Auto-Upgrade | Method |
-|---------|-------------|--------|
-| **scheduler** | YES | entrypoint.sh with advisory lock + two-DSN |
-| **memory** | YES (v2.16.0+) | entrypoint.sh with advisory lock + two-DSN |
-
-These containers run `alembic upgrade head` on start via entrypoint. No explicit
-operator action needed.
-
-## Explicit Migration Commands
-
-Services with ENTRYPOINT set on their primary command require `--entrypoint`
-override to run alembic.
-
-### Audit
-
-```bash
-docker compose -p vds-platform \
-    -f docker/docker-compose.infra.yml \
-    -f docker/docker-compose.services.yml \
-    -f docker/docker-compose.cli.yml \
-    --profile audit \
-    run --rm --no-deps --entrypoint /opt/venv/bin/alembic audit-orchestrator \
-    -c /app/audit_orchestrator/alembic.ini upgrade head
-```
-
-### Progress Report
-
-```bash
-docker compose -p vds-platform \
-    -f docker/docker-compose.infra.yml \
-    -f docker/docker-compose.services.yml \
-    -f docker/docker-compose.cli.yml \
-    --profile progress \
-    run --rm --no-deps --entrypoint /opt/venv/bin/alembic progress-report-orchestrator \
-    -c /app/progress_report_orchestrator/alembic.ini upgrade head
-```
-
-## Profiles
-
-| Profile | Services |
-|---------|----------|
-| audit | audit-orchestrator |
-| pdf | pdf-orchestrator |
-| progress | progress-report-orchestrator |
-| db-query | db-query-orchestrator |
-| vds-cli | unified router |
-| mcp-server | MCP bridge |
-| cli | all of the above |
-
-## Two-DSN Model
-
-For production deployments, set `MIGRATION_DATABASE_URL` to a superuser DSN for
-DDL during alembic. The runtime uses `DATABASE_URL` (least-privilege). If
-`MIGRATION_DATABASE_URL` is unset, entrypoints fall back to `DATABASE_URL`.

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

@@ -1,52 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Multi-Agent Orchestrator
-
-> Coordinate multiple AI agents for complex parallel tasks.
-
-## Scope
-
-- **Does:** Dispatch tasks to agent teams, aggregate results, manage conflicts, and track team progress.
-- **Does NOT:** Replace individual agent decision-making, guarantee consensus, or manage human teams.
-- **Primary users:** AI agents (team coordination), human leads (oversight), complex task runners.
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli multi-agent --help
-
-# Direct entry
-vds-cli multi-agent --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `dispatch` | Dispatch task to agents | `--task`, `--agents`, `--strategy` |
-| `aggregate` | Aggregate agent results | `--run-id`, `--method` |
-| `resolve` | Resolve conflicts | `--run-id`, `--strategy` |
-| `status` | Check team status | `--run-id` |
-
-## Common Workflows
-
-### Workflow: Parallel Code Review
-
-1. Dispatch review tasks: `vds-cli multi-agent dispatch --task "review PR #123" --agents reviewer-1,reviewer-2,reviewer-3`
-2. Wait for completion
-3. Aggregate results: `vds-cli multi-agent aggregate --run-id <id> --method consensus`
-4. Resolve conflicts if reviewers disagree
-
-## Related
-
-- **Orchestrators:** [audit](audit-triage-playbook.md), [evolution](evolution-orchestrator.md), [tasks](tasks-orchestrator.md)
-- **Confluence:** [WHO Multi-Agent](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -1,57 +0,0 @@
-<!-- diátaxis: reference -->
-
-# OpenAPI Orchestrator
-
-> OpenAPI schema validation, conversion, and client generation.
-
-## Scope
-
-- **Does:** Validate OpenAPI 3.x specs, convert between formats (JSON/YAML), generate client stubs, and extract endpoint documentation.
-- **Does NOT:** Design APIs, replace Swagger UI, or manage API gateways.
-- **Primary users:** AI agents (API review), developers (client generation), QA (contract testing).
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli openapi --help
-
-# Direct entry
-vds-cli openapi --help
-```
-
-## Key Commands
-
-| Command | Purpose | Common Flags |
-|---------|---------|-------------|
-| `validate` | Validate OpenAPI spec | `--input`, `--strict` |
-| `convert` | Convert between JSON/YAML | `--input`, `--output` |
-| `generate` | Generate client stub | `--input`, `--language`, `--output` |
-| `extract` | Extract endpoint docs | `--input`, `--path` |
-
-## Common Workflows
-
-### Workflow: Validate API Spec
-
-1. Run `vds-cli openapi validate --input api.yaml --strict`
-2. Review validation errors
-3. Fix issues and re-validate
-
-### Workflow: Generate Python Client
-
-1. Run `vds-cli openapi generate --input api.yaml --language python --output client/`
-2. Review generated client code
-3. Add to project dependencies
-
-## Related
-
-- **Orchestrators:** [schema](schema-orchestrator.md), [public_interface](public-interface-orchestrator.md)
-- **Confluence:** [WHO OpenAPI](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation)
-
-## Troubleshooting
-
-| Issue | Cause | Resolution |
-|-------|-------|------------|
-| Command not found | Orchestrator not installed | Run `uv sync --all-packages` |
-| Config missing | `~/.vds/.env` unset | Add required credentials per [AGENTS.md](../../../AGENTS.md) |
-| Permission denied | Insufficient privileges | Check Bitbucket/Confluence token scope |

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

@@ -1,194 +0,0 @@
-<!-- diátaxis: reference -->
-
-# Orchestrator Architecture
-
-The WHO CLI routes commands to 37 specialized orchestrators through a unified dispatch layer.
-
-## Routing Architecture
-
-```mermaid
-graph LR
-    A[User] -->|vds-cli <cmd>| B[Typer Router]
-    B --> C{Command Type}
-    C -->|Native| D[Built-in Commands]
-    C -->|Orchestrator| E[Router.dispatch]
-    E -->|uv run| F[Orchestrator CLI]
-    F --> G[External API]
-    D --> H[Console Output]
-    F --> H
-```
-
-### Command Dispatch Flow
-
-1. User runs `vds-cli <orchestrator> <subcommand> <args>`
-2. `vds_cli.cli` (Typer) parses the command
-3. If it's a native command (`docs`, `skills`, `env`, `lint`), execute directly
-4. If it's an orchestrator command, `router.py` dispatches via `uv run`
-5. Orchestrator CLI runs independently and returns output
-
-### Router Configuration
-
-Orchestrators are registered in `router.py` as:
-
-```python
-ORCHESTRATORS = {
-    "audit": {
-        "module": "vds_audit_orchestrator.cli",
-        "path": "audit_orchestrator",
-        "entry": "vds-audit",
-    },
-    # ... 36 more
-}
-```
-
-Each entry requires:
-- `module`: Python import path to the CLI module
-- `path`: Relative path to the orchestrator directory
-- `entry`: CLI entry point name (as defined in `pyproject.toml` `[project.scripts]`)
-
-## Orchestrator Categories
-
-### Audit & Quality
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `audit` | `vds-audit` | `vds_audit_orchestrator.cli` | Multi-repo quality audits |
-| `sonarqube` | `vds-sonarqube` | `vds_sonarqube_orchestrator.cli` | SonarQube analysis |
-| `hexagonal` | `vds-hexagonal` | `vds_hexagonal_orchestrator.cli` | Architecture compliance |
-| `public_interface` | `vds-public-interface` | `vds_public_interface_orchestrator.cli` | Module boundary checks |
-
-### Documentation
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `confluence` | `vds-confluence-cli` | `confluence_orchestrator.cli` | Confluence sync |
-| `markdown` | `vds-markdown` | `vds_markdown_orchestrator.cli` | Markdown processing |
-| `brd` | `vds-brd` | `vds_brd_orchestrator.cli` | Business requirements |
-| `spec` | `vds-spec` | `vds_spec_orchestrator.cli` | Spec validation |
-| `diagrams` | `vds-diagrams` | `vds_diagram_generator.cli` | Diagram generation |
-
-### Data & Storage
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `db_query` | `vds-db-query` | `vds_db_query_orchestrator.cli` | Database queries |
-| `elastic` | `vds-elastic` | `vds_elastic_orchestrator.cli` | ElasticSearch |
-| `schema` | `vds-schema-convert` | `vds_schema_converter.cli` | Schema conversion |
-| `excel` | `vds-excel` | `vds_excel_orchestrator.cli` | Excel processing |
-| `google_sheets` | `vds-google-sheets-cli` | `vds_google_sheets_orchestrator.cli` | Google Sheets |
-| `metabase` | `vds-metabase` | `vds_metabase_orchestrator.cli` | Metabase integration |
-
-### DevOps & Infrastructure
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `git` | `vds-git-orchestrator` | `vds_git_orchestrator.cli` | Worktree management |
-| `scheduler` | `vds-scheduler` | `vds_scheduler_orchestrator.cli` | Job scheduling |
-| `evolution` | `vds-evolution` | `vds_evolution.cli` | Ecosystem health |
-| `links` | `vds-links` | `vds_links_orchestrator.cli` | Link health |
-| `structure` | `vds-structure` | `vds_structure_orchestrator.cli` | Structure analysis |
-| `circular_dependency` | `vds-circular-dependency` | `vds_circular_dependency_orchestrator.cli` | Cycle detection |
-
-### AI & Agents
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `memory` | `vds-memory` | `vds_memory_orchestrator.cli` | AI memory |
-| `research` | `vds-research` | `vds_research_orchestrator.cli` | Research workflow |
-| `multi_agent` | `vds-multi-agent` | `vds_multi_agent_orchestrator.cli` | Parallel agents |
-| `telegram` | `vds-telegram` | `vds_telegram_orchestrator.cli` | Telegram bot |
-| `claude` | `vds-claude` | `vds_claude_orchestrator.cli` | Claude API |
-| `mcp` | `vds-mcp` | `vds_mcp_orchestrator.cli` | MCP servers |
-| `lsp` | `vds-lsp` | `vds_lsp_orchestrator.cli` | LSP integration |
-
-### Integration
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `bitbucket` | `vds-bitbucket-cli` | `vds_bitbucket_orchestrator.cli` | Bitbucket API |
-| `jira` | `vds-jira-cli` | `vds_jira_orchestrator.cli` | Jira integration |
-| `openapi` | `vds-openapi` | `vds_openapi_orchestrator.cli` | OpenAPI handling |
-| `pdf` | `vds-pdf` | `vds_pdf_orchestrator.cli` | PDF processing |
-| `intellij` | `vds-intellij` | `vds_intellij_orchestrator.cli` | IntelliJ integration |
-
-### Reporting
-
-| Orchestrator | Entry Point | Module | Purpose |
-|-------------|-------------|--------|---------|
-| `progress` | `vds-progress` | `vds_progress_orchestrator.cli` | Progress reports |
-| `grafana` | `vds-grafana` | `vds_grafana_orchestrator.cli` | Grafana dashboards |
-
-## Common Patterns
-
-### Typer CLI
-
-All orchestrators use Typer for CLI definition:
-
-```python
-import typer
-app = typer.Typer(help="Orchestrator description")
-
-@app.command()
-def main(arg: str):
-    """Command help text."""
-    ...
-
-if __name__ == "__main__":
-    app()
-```
-
-### Structlog Logging
-
-All orchestrators use structlog for structured logging:
-
-```python
-import structlog
-logger = structlog.get_logger(__name__)
-
-logger.info("operation_started", repo=repo_name, checklist=checklist_id)
-```
-
-### Settings with pydantic-settings
-
-Orchestrators use pydantic-settings for configuration:
-
-```python
-from pydantic_settings import BaseSettings
-
-class OrchestratorSettings(BaseSettings):
-    env_prefix: str = "ORCHESTRATOR_"
-    timeout: float = 30.0
-```
-
-### Error Handling
-
-Orchestrators wrap errors with context:
-
-```python
-try:
-    result = external_api.call()
-except ExternalAPIError as e:
-    raise OrchestratorError(f"API call failed: {e}") from e
-```
-
-## Extension: Adding a New Orchestrator
-
-1. Create directory under `vds-scripts/<name>_orchestrator/`
-2. Add `pyproject.toml` with `[project.scripts]` entry point
-3. Implement CLI module using Typer
-4. Register in `router.py`:
-   ```python
-   "my_orchestrator": {
-       "module": "my_orchestrator.cli",
-       "path": "my_orchestrator",
-       "entry": "vds-my-orchestrator",
-   },
-   ```
-5. Add tests in `tests/`
-6. Update `AGENTS.md` and relevant docs
-
-## See Also
-
-- [System Architecture](../explanation/system-architecture.md)
-- [Data Flow](../explanation/data-flow.md)
-- [Contribute New Orchestrator](../how-to/contribute-new-orchestrator.md)