vmware-vdi 1.0.0__tar.gz

vmware_vdi-1.0.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: vmware-vdi
+Version: 1.0.0
+Summary: VMware/Omnissa Horizon VDI intelligent operations — pools, sessions, machines, entitlements, images (MCP + CLI)
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+Keywords: ai-ops,desktop,euc,horizon,mcp,omnissa,vdi,vmware
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-policy<2.0,>=1.8.8
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.zw008/vmware-vdi -->
+
+# VMware VDI (Horizon)
+
+AI-powered VMware / Omnissa **Horizon VDI** intelligent operations — desktop pools, RDS farms, **user
+sessions**, desktop machines, entitlements, events/health, statistics, and instant-clone image push,
+through the Horizon 8 Connection Server REST API. MCP server + CLI, part of the VMware skill family.
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or
+> sponsored by VMware, Inc., Broadcom Inc., or Omnissa, LLC.** "VMware", "Horizon", and "Omnissa" are
+> trademarks of their respective owners. Source is publicly auditable under the MIT license.
+
+> **Status: in development (v1.0.0).** Design in `design/vmware-vdi-skill-design.md`. Tool surface
+> (15 read / 14 write across monitoring / statistics / management / ops actions / tasks) is landing
+> vertical by vertical — **sessions first**. Governed by the family harness (audit + policy + teaching
+> errors); authorization is delegated to the Horizon admin account's role (a read-only role refuses
+> writes at the Connection Server).
+
+## Companion skills
+
+- [vmware-aiops](https://github.com/zw008/VMware-AIops) — the vCenter VMs backing the desktops
+- [vmware-monitor](https://github.com/zw008/VMware-Monitor) — read-only vSphere monitoring
+- [vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security) — desktop microsegmentation
+
+## License
+
+MIT

vmware_vdi-1.0.0/README-CN.md

@@ -0,0 +1,42 @@
+<!-- mcp-name: io.github.zw008/vmware-vdi -->
+
+# VMware VDI (Horizon)
+
+AI 驱动的 VMware / Omnissa **Horizon VDI** 智能运维 —— 桌面池、RDS 农场、**用户会话**、桌面机器、授权、
+事件/健康/统计、即时克隆金像推送,通过 **Horizon 8 Connection Server REST API**(以 Horizon 8 为主,
+兼容最新 Omnissa Horizon,同一套 `/rest/v1` API)。MCP server + CLI,VMware skill 家族成员。
+
+> **声明**:社区维护的开源项目,**与 VMware, Inc.、Broadcom Inc.、Omnissa, LLC. 无任何隶属、背书或赞助关系。**
+> "VMware"、"Horizon"、"Omnissa" 为各自商标。源码遵循 MIT 许可,公开可审计。
+
+> **状态:v1.0.0(beta)。** REST 端点已对照官方 Horizon Server API 核实;GET 响应字段投影为防御式,
+> 待真机 Connection Server 验证(在真实 Horizon 上跑一次 `vmware-vdi init` 即可确认)。由家族 harness
+> 治理(审计 + 策略 + 教学性错误);读写授权交由 Horizon 管理账号的角色(RBAC)。
+
+## 能力(27 工具:16 读 / 11 写)
+
+| 类别 | 工具 |
+|------|------|
+| **监控** | 健康速览、会话 列表/详情、机器 列表/详情、事件列表 |
+| **统计** | 会话并发统计、按池利用率 |
+| **管理** | 池/农场/应用池/授权/镜像 列表、AD 搜索;池 启用/禁用、授权 增/删 |
+| **运维动作** | 会话 注销/断开/发消息、机器 重置/维护/移除 |
+| **任务** | 任务状态;镜像推送、任务取消 |
+
+破坏性写操作预览爆炸半径、CLI 双重确认、`--dry-run`、统一审计到 `~/.vmware/audit.db`。
+`pool_push_image` 重建整池桌面,爆炸半径最高,预览报受影响桌面数 + 在线用户数。
+
+## 快速开始
+```bash
+uv tool install vmware-vdi
+vmware-vdi init      # 友好向导:连接 Connection Server 并发现你的桌面池
+vmware-vdi doctor
+```
+
+## Companion Skills
+- [vmware-aiops](https://github.com/zw008/VMware-AIops) —— 桌面背后的 vCenter 虚机
+- [vmware-monitor](https://github.com/zw008/VMware-Monitor) —— 只读 vSphere 监控
+- [vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security) —— 桌面微隔离
+
+## License
+MIT

vmware_vdi-1.0.0/README.md

@@ -0,0 +1,27 @@
+<!-- mcp-name: io.github.zw008/vmware-vdi -->
+
+# VMware VDI (Horizon)
+
+AI-powered VMware / Omnissa **Horizon VDI** intelligent operations — desktop pools, RDS farms, **user
+sessions**, desktop machines, entitlements, events/health, statistics, and instant-clone image push,
+through the Horizon 8 Connection Server REST API. MCP server + CLI, part of the VMware skill family.
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or
+> sponsored by VMware, Inc., Broadcom Inc., or Omnissa, LLC.** "VMware", "Horizon", and "Omnissa" are
+> trademarks of their respective owners. Source is publicly auditable under the MIT license.
+
+> **Status: in development (v1.0.0).** Design in `design/vmware-vdi-skill-design.md`. Tool surface
+> (15 read / 14 write across monitoring / statistics / management / ops actions / tasks) is landing
+> vertical by vertical — **sessions first**. Governed by the family harness (audit + policy + teaching
+> errors); authorization is delegated to the Horizon admin account's role (a read-only role refuses
+> writes at the Connection Server).
+
+## Companion skills
+
+- [vmware-aiops](https://github.com/zw008/VMware-AIops) — the vCenter VMs backing the desktops
+- [vmware-monitor](https://github.com/zw008/VMware-Monitor) — read-only vSphere monitoring
+- [vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security) — desktop microsegmentation
+
+## License
+
+MIT

vmware_vdi-1.0.0/RELEASE_NOTES.md

@@ -0,0 +1,33 @@
+## v1.0.0 (beta) — first release
+
+The family's 14th skill: **vmware-vdi** — VMware/Omnissa Horizon VDI intelligent operations through the
+Horizon 8 Connection Server REST API. Independent version line (not aligned to the family's 1.8.x).
+
+**27 MCP tools (16 read / 11 write)** + full CLI parity, across monitoring / statistics / management /
+ops-actions / tasks:
+- **Sessions** — list/get, logoff, disconnect, send-message (help-desk core).
+- **Machines** — list/get, reset, enter/exit maintenance, remove.
+- **Pools** — list/get, enable/disable, **push-image** (recreates every desktop; highest blast radius in
+  the family — preview states affected-desktop + in-session-user counts).
+- **Monitoring & statistics** — one-glance health, session stats, pool utilization, audit events.
+- **Catalog & access** — farms, application pools, instant-clone images, AD search, entitlement
+  list/add/remove.
+- **Tasks** — pool-scoped task status + cancel (image push / provisioning).
+
+**Governance (family harness)**: every write goes through `@vmware_tool`/`@guarded` → `~/.vmware/audit.db`;
+destructive CLI writes double-confirm + `--dry-run`; Connection-Server text is `sanitize()`d; authorization
+is delegated to the Horizon admin role (a read-only role refuses writes at the server, un-bypassably).
+
+**Friendly onboarding**: `vmware-vdi init` connects to a Connection Server and discovers your pools,
+machines, and sessions with next-step hints.
+
+**Supported**: Horizon 8.x (primary) and the latest Omnissa Horizon (2406/2412+); same `/rest/v1` API.
+
+### Beta caveat (please read)
+REST **endpoints** are verified against the official Horizon Server API operation index. GET-response
+**field names** and a few write bodies are defensive (`.get()` with fallbacks) and **pending validation
+against a live Connection Server** — on a field-name mismatch a list reads empty rather than crashing.
+First production use should run `vmware-vdi init` on a real Horizon 8 and confirm the session/machine/pool
+projections and the apply-image / entitlement bodies; please file an issue with raw `*_get` output if a
+projection looks empty. Quality: 32 regression tests, ruff clean, bandit 0 issues, tool endpoints pinned
+to a verified spec set.

vmware_vdi-1.0.0/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Disclaimer
+Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by VMware,
+Inc., Broadcom Inc., or Omnissa, LLC.** "VMware", "Horizon", and "Omnissa" are trademarks of their
+respective owners.
+
+## Reporting Vulnerabilities
+Please open a GitHub private security advisory at https://github.com/zw008/VMware-VDI/security/advisories
+or email the maintainer. Do not file public issues for security reports.
+
+## Security Design
+
+### Credential Management
+- Passwords live only in `~/.vmware-vdi/.env` (chmod 600), obfuscated to `b64:` at rest (obfuscation, not
+  encryption; defeats casual grep / shoulder-surfing). Config files hold host/username/domain only.
+- Per-target env vars `VMWARE_VDI_<TARGET>_PASSWORD` can be injected from a secret manager.
+- Username + password are resolved together on every call so a rotated credential never half-updates.
+
+### Authorization — delegated to Horizon RBAC
+The skill ships full read+write and does not gate read-vs-write itself. Point a target at a read-only
+Horizon admin role and every write is refused at the Connection Server, un-bypassably — the one place the
+control cannot be stepped around by a shell.
+
+### Destructive-operation safety
+`session_logoff`, `machine_reset`, `machine_remove`, `pool_set_enabled` (disable), `entitlement_remove`,
+`pool_push_image`, and `task_cancel` preview their blast radius, require CLI double-confirmation, and
+support `--dry-run`. `pool_push_image` (recreates every desktop in a pool) reports affected-desktop and
+in-session-user counts before any confirm.
+
+### SSL/TLS Verification
+On by default. `verify_ssl: false` is per-target and intended only for self-signed lab certificates.
+
+### Transitive Dependencies
+Runtime deps: httpx, typer, rich, pyyaml, python-dotenv, mcp, and `vmware-policy` (the family's shared
+audit/policy harness). No urllib3, no requests.
+
+### Prompt Injection Protection
+All Connection-Server-supplied text is passed through `vmware_policy.sanitize()` (truncation +
+C0/C1 control-character stripping) before it reaches the model.
+
+## Static Analysis
+```bash
+uvx bandit -r vmware_vdi/     # 0 issues at all severities as of v1.0.0
+```
+
+## Supported Versions
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | ✅ (beta) |

vmware_vdi-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vmware-vdi"
+version = "1.0.0"
+description = "VMware/Omnissa Horizon VDI intelligent operations — pools, sessions, machines, entitlements, images (MCP + CLI)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
+keywords = ["vmware", "omnissa", "horizon", "vdi", "desktop", "euc", "mcp", "ai-ops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "typer>=0.12,<1.0",
+    "rich>=13.0,<15.0",
+    "pyyaml>=6.0,<7.0",
+    "python-dotenv>=1.0,<2.0",
+    "mcp[cli]>=1.10,<2.0",
+    "vmware-policy>=1.8.8,<2.0",
+]
+
+[project.scripts]
+vmware-vdi = "vmware_vdi.cli:app"
+vmware-vdi-mcp = "vmware_vdi.mcp_server.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vmware_vdi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "capability: Capability evals — scored trends, not pass/fail gates. Excluded from the default run. Run with: pytest -m capability",
+]
+addopts = "-m 'not capability'"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<10.0",
+    "pytest-cov>=5.0,<8.0",
+    "ruff>=0.5,<1.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint.per-file-ignores]
+# 踩坑 #33: MCP-server modules are reflected by FastMCP/Pydantic at import time.
+# Tool-signature annotations must stay `Optional[X]` — the PEP 604 `X | None` form
+# can raise `subclass() arg 1 must be a class` under older interpreters. Never let
+# pyupgrade (UP007/UP045) rewrite them in the reflected files.
+"vmware_vdi/mcp_server/**/*.py" = ["UP007", "UP045"]

vmware_vdi-1.0.0/server.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.zw008/vmware-vdi",
+  "description": "VMware/Omnissa Horizon VDI intelligent operations — pools, sessions, machines, entitlements, images",
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "registry_base_url": "https://pypi.org",
+      "identifier": "vmware-vdi",
+      "version": "1.0.0",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "repository": {
+    "url": "https://github.com/zw008/VMware-VDI",
+    "source": "github"
+  }
+}

vmware_vdi-1.0.0/skills/vmware-vdi/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: vmware-vdi
+description: >
+  Use this skill whenever the user needs to operate a VMware/Omnissa Horizon VDI environment via its
+  Connection Server: list and manage desktop pools, RDS farms and published apps, inspect and act on
+  user sessions (log off, disconnect, send message), manage desktop machines (reset, maintenance,
+  remove), view and change entitlements, read Horizon events/health/statistics, and push instant-clone
+  golden images. Always use this skill for "log off VDI user", "reset this desktop", "why is the desktop
+  pool not provisioning", "push the new image to the pool", "list Horizon sessions", "who is entitled to
+  the pool", "VDI health" — when the context is explicitly Horizon / Omnissa / VDI / desktop-pool /
+  RDS-farm. Do NOT use for the underlying vCenter VM lifecycle/power/snapshot/migrate (use vmware-aiops),
+  read-only vSphere monitoring (use vmware-monitor), or NSX microsegmentation (use vmware-nsx-security).
+  This skill manages the Horizon broker layer; vmware-aiops manages the vCenter VMs backing the desktops.
+installer:
+  kind: uv
+  package: vmware-vdi
+allowed-tools:
+  - Bash
+metadata: {"openclaw":{"requires":{"env":["VMWARE_VDI_CONFIG"],"bins":["vmware-vdi"],"config":["~/.vmware-vdi/config.yaml"]},"primaryEnv":"VMWARE_VDI_CONFIG"}}
+---
+
+# VMware VDI (Horizon)
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or
+> sponsored by VMware, Inc., Broadcom Inc., or Omnissa, LLC.** "VMware", "Horizon", and "Omnissa" are
+> trademarks of their respective owners. Source is publicly auditable under the MIT license.
+
+Horizon VDI intelligent operations for the VMware skill family — desktop pools, RDS farms, **user
+sessions**, desktop machines, entitlements, events/health/statistics, and instant-clone image push,
+through the **Horizon 8 Connection Server REST API** (primary; also targets the latest Omnissa Horizon,
+which shares the same `/rest/v1` API lineage).
+
+> **Companion skills**: [vmware-aiops](https://github.com/zw008/VMware-AIops) (the vCenter VMs backing
+> the desktops), [vmware-monitor](https://github.com/zw008/VMware-Monitor) (read-only vSphere),
+> [vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security) (desktop microsegmentation).
+
+> **Status: v1.0.0 (beta).** Endpoints are verified against the official Horizon Server API; GET-response
+> field projections are defensive and pending validation against a live Connection Server (run
+> `vmware-vdi init` on a real Horizon once to confirm). Governed by the family harness (audit + policy +
+> teaching errors); authorization is delegated to the Horizon admin account's role.
+
+## What This Skill Does
+
+| Category | Tools | Count | Read/Write |
+|----------|-------|:-----:|:----------:|
+| **Monitoring** | health summary, session list/get, machine list/get, event list | 6 | 6 R |
+| **Statistics** | session concurrency stats, per-pool utilization | 2 | 2 R |
+| **Management** | pool list/get, farm list, app-pool list, entitlement list, image list, AD search; pool enable/disable, entitlement add/remove | 9 | 7 R / 2 W |
+| **Ops actions** | session logoff/disconnect/message, machine reset/maintenance/remove | 6 | 6 W |
+| **Tasks** | task status; image push, task cancel | 3 | 1 R / 2 W |
+
+**27 MCP tools (16 read / 11 write).** Reads are strictly non-destructive. Writes preview their blast
+radius, are double-confirmed at the CLI, and are audit-logged.
+
+## Quick Install
+
+```bash
+uv tool install vmware-vdi
+vmware-vdi init      # friendly setup: connect to a Connection Server + discover your pools
+vmware-vdi doctor    # verify config / credentials / connectivity
+```
+
+## When to Use This Skill
+
+Use vmware-vdi for the **Horizon broker layer**: desktop pools, RDS farms, published apps, **user
+sessions** (logoff/disconnect/message), desktop machine state (reset/maintenance/remove), entitlements,
+Horizon events/health/statistics, and **instant-clone image push** — when the context is explicitly
+Horizon / Omnissa / VDI / desktop-pool / RDS-farm.
+
+**Do NOT use when**: the task is the underlying vCenter VM (power/snapshot/clone/migrate → **vmware-aiops**),
+read-only vSphere inventory/alarms (→ **vmware-monitor**), or NSX microsegmentation of the desktops
+(→ **vmware-nsx-security**). A Horizon desktop's *backing VM* is aiops; the *session/pool/broker* is vdi.
+
+## Related Skills — Skill Routing
+
+| The user wants… | Skill |
+|-----------------|-------|
+| Log off / reset / re-image a Horizon desktop or session | **vmware-vdi** (this) |
+| Power/snapshot/clone/migrate the backing vCenter VM | vmware-aiops |
+| Read-only vSphere inventory / alarms / host health | vmware-monitor |
+| Microsegment the desktop pool network | vmware-nsx-security |
+| Multi-step VDI workflow with approval + rollback | vmware-pilot |
+
+## Common Workflows
+
+**1. Help-desk: a user's desktop is stuck.**
+```
+vmware-vdi session list --user alice          # find their session + state
+vmware-vdi machine list --state AGENT_UNREACHABLE   # is the desktop broken?
+vmware-vdi session logoff --user alice --dry-run    # preview blast radius (which sessions)
+vmware-vdi session logoff --user alice        # double-confirm, then logs off + audits
+```
+*Failure branch*: if `session list` returns a teaching 404/auth error, run `vmware-vdi doctor` — a
+read-only Horizon role is enough for the reads but the account must be able to reach the Connection Server.
+
+**2. Patch night: push a new golden image to a pool.**
+```
+vmware-vdi image list                         # find the base VM + snapshot
+vmware-vdi pool push-image --id pool-fin --dry-run   # BLAST RADIUS: N desktops, M logged-in users
+vmware-vdi pool set-enabled --id pool-fin --disable  # optional: stop new logins first
+vmware-vdi pool push-image --id pool-fin      # double-confirm; returns a task
+vmware-vdi task status --pool pool-fin         # track progress
+```
+*Failure branch*: if the preview shows logged-in users you did not expect, `session send-message --user …`
+to warn them, or push with `--force-logoff` only after confirming impact.
+
+**3. Onboard a group to a pool.**
+```
+vmware-vdi ad-search "Finance"                # resolve the AD group → its SID
+vmware-vdi entitlement add --pool pool-fin --sid <SID>
+vmware-vdi entitlement list --pool pool-fin   # verify
+```
+*Failure branch*: `ad-search` returning nothing usually means the domain in `~/.vmware-vdi/config.yaml`
+is wrong — re-run `vmware-vdi init --force`.
+
+## Usage Mode
+
+- **CLI** — interactive help-desk work, scripting, small/local models (lower context cost).
+- **MCP** — agent-driven operations with structured output; run `vmware-vdi mcp` (an installed console
+  script, so no `uvx` network re-resolve — works through enterprise TLS proxies).
+
+## MCP Tools (27 — 16 read, 11 write)
+
+| Category | Tools | R/W |
+|----------|-------|:---:|
+| Monitoring | `health_summary`, `session_list`, `session_get`, `machine_list`, `machine_get`, `event_list` | Read |
+| Statistics | `session_stats`, `pool_utilization` | Read |
+| Management (read) | `pool_list`, `pool_get`, `farm_list`, `app_pool_list`, `entitlement_list`, `image_list`, `ad_user_search` | Read |
+| Tasks (read) | `task_status` | Read |
+| Ops actions | `session_logoff`, `session_disconnect`, `session_send_message`, `machine_reset`, `machine_maintenance`, `machine_remove` | Write |
+| Management (write) | `pool_set_enabled`, `entitlement_add`, `entitlement_remove` | Write |
+| Tasks (write) | `pool_push_image`, `task_cancel` | Write |
+
+**List envelope**: every `*_list` tool returns `{items, returned, limit, total, truncated, hint}` — read
+rows from `items` and check `truncated` before concluding a listing is complete; empty `items` with
+`truncated:false` means checked-and-none, not a failure. Lists are fetched with server-side pagination.
+
+**Blast radius (normative)**: `pool_push_image` recreates **every desktop in the pool** — the highest
+single-call blast radius in the family. Its preview states affected-desktop and in-session-user counts
+before any confirm. `session_logoff` / `machine_reset` / `machine_remove` state their affected users/
+machines and require double confirmation at the CLI.
+
+**Read/write split**: 16 read-only tools (`[READ]` docstring marker), 11 modify state. All writes are
+audit-logged; destructive ones (`session_logoff`, `machine_reset`, `machine_remove`, `pool_set_enabled`
+disable, `entitlement_remove`, `pool_push_image`, `task_cancel`) require CLI double-confirmation and
+support `--dry-run`.
+
+## CLI Quick Reference
+
+```bash
+vmware-vdi init                                          # friendly setup + pool discovery
+vmware-vdi health                                        # one-glance VDI health
+vmware-vdi stats                                         # session concurrency statistics
+vmware-vdi utilization                                   # per-pool desktop utilization
+vmware-vdi session list [--user U] [--pool P] [--state CONNECTED]
+vmware-vdi session logoff --user U [--dry-run]           # double-confirm
+vmware-vdi machine list [--pool P] [--state AGENT_UNREACHABLE]
+vmware-vdi machine reset --id M [--dry-run]              # hard reset; double-confirm
+vmware-vdi machine maintenance --id M --enter|--exit
+vmware-vdi pool list
+vmware-vdi pool set-enabled --id P --enable|--disable
+vmware-vdi pool push-image --id P [--force-logoff] [--dry-run]   # highest blast radius
+vmware-vdi task status --pool P [--task T]
+vmware-vdi ad-search "<name>"                            # resolve AD SID for entitlement
+vmware-vdi entitlement add|remove --pool P --sid <SID>
+```
+Full list: `references/cli-reference.md`.
+
+## Troubleshooting
+
+- **`Password not found. Set environment variable: VMWARE_VDI_<TARGET>_PASSWORD`** — run `vmware-vdi init`
+  (writes `~/.vmware-vdi/.env`, 0600), or export the var manually.
+- **Login fails (HTTP 401/400)** — check `username`/`domain` in `~/.vmware-vdi/config.yaml`; Horizon
+  authenticates against the AD `domain`. A local Connection Server admin leaves `domain` blank.
+- **`certificate could not be verified`** — for a self-signed lab cert set `verify_ssl: false` for that
+  target in the config.
+- **A write is refused with "read-only role"** — that is RBAC working as designed. Point the target at a
+  Horizon admin role with write privilege, or keep the read-only account for read commands only.
+- **`session list --pool` or a push-image preview shows 0 where you expect users** — on your Horizon
+  version a field name may differ; this is a beta known-limitation, please file an issue with the raw
+  `session_get` output so the projection can be pinned.
+
+## Audit & Safety
+
+1. **Source Code** — https://github.com/zw008/VMware-VDI (MIT).
+2. **Config File Contents** — `config.yaml` holds host/username/domain only; passwords live in
+   `~/.vmware-vdi/.env` (0600, obfuscated to `b64:` at rest — obfuscation, not encryption).
+3. **Webhook Data Scope** — none. This skill makes no outbound calls except to the configured
+   Connection Server.
+4. **TLS Verification** — on by default; `verify_ssl: false` is per-target and only for self-signed labs.
+5. **Prompt Injection Protection** — all Connection-Server-supplied text (user names, machine/pool names,
+   event messages) passes through `vmware_policy.sanitize()` (truncation + control-char stripping).
+6. **Least Privilege** — authorization is the Horizon account's job: a read-only Horizon admin role
+   refuses every write at the Connection Server, un-bypassably. All writes are recorded in
+   `~/.vmware/audit.db`. See `references/setup-guide.md`.
+
+## License
+
+MIT

vmware_vdi-1.0.0/skills/vmware-vdi/references/capabilities.md

@@ -0,0 +1,54 @@
+# vmware-vdi — Capabilities
+
+27 MCP tools (16 read / 11 write) over the Horizon 8 Connection Server REST API. Every tool accepts an
+optional `target`. Typical response tokens are estimates for a small estate; lists paginate at 50.
+
+## Monitoring (6 read)
+| Tool | R/W | Returns | ~tokens |
+|------|:---:|---------|:------:|
+| `health_summary` | R | session totals by state, problem-machine count, pool enabled/disabled | 80–200 |
+| `session_list` | R | id, user, type, state, protocol, pool_id, machine_id, start_time (filter user/pool/state) | 60–500 |
+| `session_get` | R | one session's projection | 40–100 |
+| `machine_list` | R | id, name, pool_id, state, user, agent_version, base_image (filter pool/state) | 60–500 |
+| `machine_get` | R | one machine's projection | 40–100 |
+| `event_list` | R | time, severity, type, module, user, machine, message (filter severity) | 100–600 |
+
+## Statistics (2 read)
+| Tool | R/W | Returns | ~tokens |
+|------|:---:|---------|:------:|
+| `session_stats` | R | current concurrent, by-state, by-protocol, top pools | 80–200 |
+| `pool_utilization` | R | per-pool total/available/in-use/error + utilization % | 80–300 |
+
+## Management (7 read / 2 write)
+| Tool | R/W | Notes | ~tokens |
+|------|:---:|-------|:------:|
+| `pool_list` / `pool_get` | R | pools: type, enabled, assignment | 60–300 |
+| `farm_list` | R | RDS farms: type, enabled, server count | 40–200 |
+| `app_pool_list` | R | published apps: farm, enabled, executable | 40–300 |
+| `entitlement_list` | R | AD principals entitled to a pool | 40–300 |
+| `image_list` | R | instant-clone base VMs + snapshots | 60–400 |
+| `ad_user_search` | R | resolve AD name → SID (for `entitlement_add`) | 40–200 |
+| `pool_set_enabled` | W | enable/disable pool (idempotent, preview) | 40–120 |
+| `entitlement_add` / `entitlement_remove` | W | grant/revoke pool access by SID (preview) | 40–120 |
+
+## Ops actions (6 write) — help-desk
+| Tool | R/W | Risk | Blast radius |
+|------|:---:|:----:|--------------|
+| `session_send_message` | W | low | informational, no disruption |
+| `session_disconnect` | W | medium | one session, state preserved |
+| `session_logoff` | W | high | kicks the user (profile write-back) |
+| `machine_maintenance` | W | medium | drains a machine (no new sessions) |
+| `machine_reset` | W | high | hard reset — user loses unsaved state |
+| `machine_remove` | W | high | removes from pool; deletes VM for instant clones |
+
+## Tasks (1 read / 2 write)
+| Tool | R/W | Notes |
+|------|:---:|-------|
+| `task_status` | R | pool-scoped task status/progress (or all tasks for the pool) |
+| `pool_push_image` | W | **critical** — apply pending image; recreates EVERY desktop; preview states affected desktops + in-session users |
+| `task_cancel` | W | cancel a running pool task (applied work is not rolled back) |
+
+**Beta note (踩坑 #36)**: REST endpoints are verified against the official Horizon Server API operation
+index. GET-response *field names* are defensive (`.get()` with fallbacks) and pending validation against a
+live Connection Server — a mismatch yields empty results, not a crash. First real-Horizon use should
+confirm the `session`/`machine`/`pool` projections and the `apply-image` / entitlement bodies.

vmware_vdi-1.0.0/skills/vmware-vdi/references/cli-reference.md

@@ -0,0 +1,55 @@
+# vmware-vdi — CLI Reference
+
+All commands accept `--target/-t <name>` (config target) and `--config/-c <path>` (alternate config file).
+Destructive commands accept `--dry-run` (preview only) and interactively double-confirm.
+
+## Setup & diagnostics
+```bash
+vmware-vdi init [--force] [--skip-test]     # friendly setup: prompt, write config + .env, test, discover pools
+vmware-vdi doctor                           # config / credentials / connectivity checks
+vmware-vdi mcp                              # run the MCP server (stdio) — the primary MCP entry point
+```
+
+## Monitoring & statistics (read-only)
+```bash
+vmware-vdi health                           # session totals, problem machines, pool availability
+vmware-vdi stats                            # concurrency by state/protocol, busiest pools
+vmware-vdi utilization                      # per-pool total/available/in-use/error + utilization %
+vmware-vdi events [--severity ERROR]        # recent Horizon audit events (newest first)
+```
+
+## Sessions
+```bash
+vmware-vdi session list [--user U] [--pool P] [--state CONNECTED|DISCONNECTED|PENDING]
+vmware-vdi session logoff [--id S] [--user U] [--dry-run]        # kicks the user; double-confirm
+vmware-vdi session disconnect [--id S] [--user U] [--dry-run]    # state preserved; double-confirm
+vmware-vdi session message "<text>" [--user U] [--id S] [--type INFO|WARNING|ERROR]
+```
+
+## Machines
+```bash
+vmware-vdi machine list [--pool P] [--state AGENT_UNREACHABLE|ERROR|...]
+vmware-vdi machine reset --id M [--dry-run]                      # hard reset; double-confirm
+vmware-vdi machine maintenance --id M --enter|--exit [--dry-run] # double-confirm
+vmware-vdi machine remove --id M [--dry-run]                     # deletes VM (instant clone); double-confirm
+```
+
+## Pools, images, tasks
+```bash
+vmware-vdi pool list
+vmware-vdi pool set-enabled --id P --enable|--disable [--dry-run]  # disable stops NEW sessions
+vmware-vdi pool push-image --id P [--force-logoff] [--dry-run]     # recreates EVERY desktop; double-confirm
+vmware-vdi images                                                  # instant-clone base VMs + snapshots
+vmware-vdi task status --pool P [--task T]                        # track an image push / provisioning
+vmware-vdi task cancel --pool P --task T [--dry-run]              # double-confirm
+```
+
+## Farms, apps, entitlements
+```bash
+vmware-vdi farm list
+vmware-vdi app-pool list
+vmware-vdi ad-search "<name>"                                     # resolve AD user/group → SID
+vmware-vdi entitlement list --pool P
+vmware-vdi entitlement add --pool P --sid <SID> [--sid <SID> ...] [--dry-run]
+vmware-vdi entitlement remove --pool P --sid <SID> [--dry-run]   # double-confirm
+```