vmware-debug 1.6.1__tar.gz

vmware_debug-1.6.1/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.log
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+config.yaml
+.agents/
+.claude/
+.trae/
+skills-lock.json
+tests/fixtures/token_corpus/
+.DS_Store

vmware_debug-1.6.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: vmware-debug
+Version: 1.6.1
+Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+Keywords: ai-ops,debug,diagnostics,mcp,rca,troubleshooting,vmware,vsphere
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-policy<2.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.zw008/vmware-debug -->
+
+# VMware Debug
+
+> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
+> is built and tested; README, `server.json`, full reference docs, and packaging
+> polish are still landing. Not yet published to PyPI.
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
+> "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
+> license.
+
+The diagnostic brain of the VMware skill family. You bring the symptom (an error,
+a log dump, a slow VM); this skill runs a systematic investigation, correlates
+events from the other skills into one timeline, ranks root-cause hypotheses, and
+tells you what to check next. It is **read-only** — it never changes anything and
+never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
+`vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
+advisor/executor split.
+
+See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
+methodology, the event-envelope contract, and symptom routing.
+
+## MCP tools
+
+| Tool | What |
+|---|---|
+| `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
+| `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
+
+## License
+
+MIT.

vmware_debug-1.6.1/README-CN.md

@@ -0,0 +1,45 @@
+<!-- mcp-name: io.github.zw008/vmware-debug -->
+
+# VMware Debug（中文）
+
+> **声明**：本项目为社区维护的开源项目，**与 VMware, Inc. 或 Broadcom Inc. 无任何隶属、
+> 背书或赞助关系。** "VMware"、"vSphere" 为 Broadcom 商标。源码以 MIT 许可证公开可审计。
+
+VMware skill 家族的**诊断大脑**。你给出症状（报错、日志、变慢的 VM），它来跑系统化排查：
+把其它 skill 取到的事件关联成一条时间线、检测突刺、给根因假设排序，并告诉你下一步该查什么。
+**只读**——从不修改任何东西，也从不执行修复。修复一律路由给 vmware-aiops（单步）或
+vmware-pilot（多步、带审批门控），完全复刻 vmware-harden → vmware-pilot 的「顾问/执行」分工。
+
+## 配套 Skill
+
+| 需求 | Skill |
+|---|---|
+| 故障关联 / 根因 | **vmware-debug**（本项目） |
+| 集中日志检索 | vmware-log-insight（把 `log_search` 结果喂给它） |
+| vCenter 事件与告警 | vmware-monitor |
+| 指标 / 异常 | vmware-aria |
+| 执行修复 | vmware-aiops（单步）/ vmware-pilot（多步门控） |
+
+## 安装
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # 看它能诊断哪些症状类别
+```
+
+## MCP 工具（2 个，全只读）
+
+- `incident_timeline`：把已取到的事件关联成 时间线 + 突刺 + 排序后的根因假设 + 下一步检查建议
+- `list_symptom_categories`：症状类别及对应的排查路由（不知道查什么时用它）
+
+**事件信封**：`{ts, source, severity, entity, text, fields}`。agent 把各源事件归一成此形状再交给
+debug；debug 因此与其它包零运行时依赖。
+
+## 安全
+
+结构上只读、离线、无凭据：不连任何 vCenter/NSX/Aria，没有可破坏面，也没有秘密可泄露。
+详见 [SECURITY.md](SECURITY.md)。
+
+## 许可证
+
+MIT。

vmware_debug-1.6.1/README.md

@@ -0,0 +1,34 @@
+<!-- mcp-name: io.github.zw008/vmware-debug -->
+
+# VMware Debug
+
+> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
+> is built and tested; README, `server.json`, full reference docs, and packaging
+> polish are still landing. Not yet published to PyPI.
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
+> "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
+> license.
+
+The diagnostic brain of the VMware skill family. You bring the symptom (an error,
+a log dump, a slow VM); this skill runs a systematic investigation, correlates
+events from the other skills into one timeline, ranks root-cause hypotheses, and
+tells you what to check next. It is **read-only** — it never changes anything and
+never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
+`vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
+advisor/executor split.
+
+See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
+methodology, the event-envelope contract, and symptom routing.
+
+## MCP tools
+
+| Tool | What |
+|---|---|
+| `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
+| `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
+
+## License
+
+MIT.

vmware_debug-1.6.1/RELEASE_NOTES.md

@@ -0,0 +1,26 @@
+## v1.6.1 (2026-06-24) — initial release
+
+First release of **vmware-debug**: the read-only diagnostic brain of the VMware
+skill family. You bring the symptom; it runs the investigation, correlates
+events from the other skills into one timeline, ranks root-cause hypotheses, and
+routes remediation to vmware-aiops / vmware-pilot. It never writes and never
+executes fixes (advisor/executor split, mirroring vmware-harden → vmware-pilot).
+
+### Added
+- **2 read-only MCP tools**: `incident_timeline` (correlate pre-fetched events
+  into a timeline + z-score spikes + ranked hypotheses + next-check ideas) and
+  `list_symptom_categories` (the symptom→skill routing catalogue).
+- **Unified event envelope** + tolerant normalizer so debug stays source-agnostic
+  with zero runtime dependency on the other skill packages — the agent fans out
+  to each skill's read tools and feeds events here (avoids cross-skill coupling,
+  踩坑 #21/#32).
+- **Pure correlation engine** (timeline merge, time-binning, spike detection,
+  hypothesis ranking, symptom routing) — fully unit-tested offline.
+- **Typer CLI**: `triage`, `categories`, `version`, `mcp`. The `mcp` entry point
+  needs no network at startup (proxy-safe, 踩坑 #25).
+- SKILL.md + references (event-envelope contract, symptom routing, playbooks).
+
+### Notes
+- Read-only by construction; remediation is routed, never executed.
+- `parse_timestamp` rejects implausible/garbage timestamps loudly rather than
+  silently landing at the epoch.

vmware_debug-1.6.1/SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+## Disclaimer
+
+This is a community-maintained open-source project and is **not affiliated with,
+endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
+"vSphere" are trademarks of Broadcom. Source code is publicly auditable at
+[github.com/zw008/VMware-Debug](https://github.com/zw008/VMware-Debug) under the
+MIT license.
+
+## Reporting Vulnerabilities
+
+Report security issues via a GitHub private security advisory on the repository,
+or by email to the maintainer. Please do not open public issues for security bugs.
+
+## Security Design
+
+### Read-only and offline by construction
+vmware-debug has **no write tools, no network access, and no credentials**. It
+does not connect to vCenter, NSX, Aria, or any appliance. Its tools are pure
+functions over event data the orchestrating agent has already fetched with the
+other skills' read tools. There is no destructive surface and no secret to leak.
+
+### No remediation execution
+debug only *diagnoses* and *recommends*. Any fix is routed to vmware-aiops
+(single op, with its own confirmation) or vmware-pilot (multi-step, approval-gated,
+audited). The safety gates live in those skills, not here.
+
+### No cross-skill coupling
+debug imports none of the other skill packages at runtime. Events arrive as plain
+dicts (the unified event envelope), so there is no transitive dependency surface.
+
+### Prompt-injection consideration
+debug operates on text the agent supplies. Its outputs are structured data
+(timelines, hypotheses, routing strings); it does not execute or shell out to
+anything based on event content.
+
+## Static Analysis
+
+```bash
+uvx bandit -r vmware_debug/ mcp_server/
+```
+
+Release bar: 0 Medium-or-higher severity findings.
+
+## Supported Versions
+
+The latest released version receives fixes. Versions are kept aligned across the
+VMware skill family.

vmware_debug-1.6.1/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""stdio MCP server package for vmware-debug."""

vmware_debug-1.6.1/mcp_server/server.py

@@ -0,0 +1,78 @@
+"""vmware-debug MCP server entry point.
+
+Tools are defined in vmware_debug.mcp.tools (so audit logs see skill=debug).
+This module wires them into a FastMCP server and provides the stdio entry point.
+
+Note: signatures here use typing.Optional, never PEP 604 ``X | None`` — FastMCP
+reflects these at registration and ``X | None`` crashes on Python 3.10 + older
+mcp/pydantic (CLAUDE.md 踩坑 #33).
+"""
+
+import sys
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from vmware_debug.mcp import tools as t
+
+
+def build_server() -> FastMCP:
+    """Construct and configure the MCP server."""
+    server = FastMCP("vmware-debug")
+
+    @server.tool(name="incident_timeline")
+    def _incident_timeline_impl(
+        events: list[dict],
+        bin_seconds: Optional[float] = None,
+        z_threshold: float = 2.0,
+        top_n: int = 5,
+    ) -> dict:
+        """[READ] Correlate already-fetched VMware events into one incident view.
+
+        WHEN: after you've pulled events for an incident from the data-source
+        skills (vmware-monitor event_list/alarm_list, vmware-aria alerts/anomaly,
+        vmware-log-insight log_search/log_aggregate, vmware-nsx) — feed them all
+        here to find what correlates and where to look next. This tool does NOT
+        fetch anything itself; it has no vCenter/network access.
+
+        INPUT: events = list of event envelopes, each {ts, source, severity,
+        entity, text, fields} (ts may be ISO-8601, epoch seconds, or millis;
+        severity is normalised). Optional: bin_seconds (time-bin width; auto if
+        omitted), z_threshold (spike sensitivity, default 2.0), top_n (max
+        hypotheses, default 5).
+
+        RETURNS: {event_count, window, spikes (anomalous time bins), hypotheses
+        (ranked root-cause candidates, each with a suggested_check), next_checks
+        (concrete ideas for what to investigate next, including which skill/tool
+        to run)}.
+
+        GOTCHAS: read-only and stateless — nothing is executed. Remediation is
+        routed to vmware-aiops (single fix) or vmware-pilot (multi-step, gated).
+        A malformed event raises ValueError naming its index."""
+        return t.incident_timeline(events, bin_seconds, z_threshold, top_n)
+
+    @server.tool(name="list_symptom_categories")
+    def _list_symptom_categories_impl() -> list[dict]:
+        """[READ] List the symptom categories vmware-debug recognises and, for
+        each, example keywords and the suggested next check (which skill/tool to
+        run). Takes no parameters. Use this when you don't yet know what to look
+        at — it turns "something's wrong" into concrete investigation steps.
+        Read-only; no network access."""
+        return t.list_symptom_categories()
+
+    return server
+
+
+def main() -> None:
+    """Entry point for `vmware-debug-mcp` (stdio transport)."""
+    if sys.version_info < (3, 11):
+        sys.exit(
+            "vmware-debug-mcp requires Python >= 3.11 (FastMCP schema reflection "
+            "is unreliable on 3.10). Reinstall under 3.11+: "
+            "uv tool install --python 3.11 vmware-debug"
+        )
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

vmware_debug-1.6.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vmware-debug"
+version = "1.6.1"
+description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
+keywords = ["vmware", "vsphere", "debug", "troubleshooting", "diagnostics", "rca", "mcp", "ai-ops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "typer>=0.12,<1.0",
+    "rich>=13.0,<15.0",
+    "mcp[cli]>=1.10,<2.0",
+    "vmware-policy>=1.0.0,<2.0",
+]
+
+[project.scripts]
+vmware-debug = "vmware_debug.cli:app"
+vmware-debug-mcp = "mcp_server.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vmware_debug", "mcp_server"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<10.0",
+    "pytest-cov>=5.0,<8.0",
+    "ruff>=0.5,<1.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

vmware_debug-1.6.1/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.zw008/vmware-debug",
+  "title": "VMware Debug",
+  "description": "VMware diagnostic brain: read-only incident correlation (timeline, spikes, ranked root-cause hypotheses) and next-check routing across the VMware skill family — 2 MCP tools.",
+  "repository": {
+    "url": "https://github.com/zw008/VMware-Debug",
+    "source": "github"
+  },
+  "version": "1.6.1",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "vmware-debug",
+      "version": "1.6.1",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

vmware_debug-1.6.1/skills/vmware-debug/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: vmware-debug
+description: >
+  Use this skill whenever the user is troubleshooting a VMware/vSphere problem —
+  a reported error, an exception, a log dump, a slow or failed VM, a host that
+  went sideways — and needs help locating the root cause. It is the diagnostic
+  brain of the VMware family: it drives a systematic investigation, pulls the
+  right signals from the other skills, correlates events into one timeline,
+  ranks root-cause hypotheses, and tells you what to check next even when you
+  don't know where to start. Always use this skill for "diagnose this VMware
+  issue", "why is my VM slow", "troubleshoot this vSphere error", "what does
+  this log mean", "help me figure out what broke" when the context is explicitly
+  VMware/vSphere/ESXi/NSX. It is READ-ONLY: it never changes anything. Do NOT
+  use it to execute fixes — single fixes go to vmware-aiops, multi-step gated
+  remediation goes to vmware-pilot. Do NOT use it for routine inventory or
+  health checks with no problem to solve — use vmware-monitor.
+installer:
+  kind: uv
+  package: vmware-debug
+allowed-tools:
+  - Bash
+metadata: {"openclaw":{"requires":{"bins":["vmware-debug"]},"primaryEnv":"NONE"}}
+---
+
+# VMware Debug
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and "vSphere"
+> are trademarks of Broadcom. Source is publicly auditable under the MIT license.
+
+The diagnostic brain of the VMware skill family. You bring the symptom; this skill
+runs the investigation and points at the root cause. It **reads and reasons** — it
+never writes. Companion skills do the data collection and the fixing.
+
+## What This Skill Does
+
+| Category | What | Read or Write |
+|---|---|---|
+| Incident correlation | Merge events from many sources into one timeline, detect spikes | Read |
+| Root-cause ranking | Score symptom clusters, surface the most likely cause first | Read |
+| Next-check ideas | Suggest exactly what to look at next (which skill/tool) when you're stuck | Read |
+| Remediation routing | Hand the fix to vmware-aiops (single) or vmware-pilot (gated, multi-step) | Read (routes only) |
+
+**Zero write tools. Zero network access of its own.** It correlates data the agent
+has already gathered with the other skills' read tools.
+
+## Quick Install
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # see what it can diagnose
+```
+
+## When to Use This Skill
+
+Use it when there is a **problem to solve**: an error message, a stack of logs, an
+alarm storm, "my VM won't power on", "storage feels slow", "the host disconnected".
+
+- Need raw inventory/health with no incident? → **vmware-monitor**
+- Need to actually run a fix? → **vmware-aiops** (single op) or **vmware-pilot** (gated workflow)
+- Need metrics/anomalies? → **vmware-aria**; centralized logs? → **vmware-log-insight**
+
+**Do NOT use when** there is nothing wrong (routine listing → monitor), or when the
+user wants the fix executed (→ aiops/pilot). This skill stops at the diagnosis and
+a recommended plan.
+
+## Related Skills — Skill Routing
+
+| Symptom touches | Pull signals from | Then |
+|---|---|---|
+| Storage / datastore / vSAN | vmware-storage, vmware-log-insight | rank → route fix to aiops/pilot |
+| Network / firewall / vMotion | vmware-nsx, vmware-nsx-security | run traceflow, check DFW |
+| CPU / memory contention | vmware-aria (metrics/anomalies) | rightsizing via pilot |
+| HA / DRS / cluster | vmware-monitor, vmware-aiops | cluster remediation via pilot |
+| Power / clone / snapshot | vmware-aiops, vmware-monitor | task status, then fix via aiops |
+| Auth / cert / login | check creds & cert; (security) | fix config/.env |
+
+## Common Workflows
+
+### 1. "Here's a pile of logs / alarms — what broke?"
+1. Collect events with the data-source skills (e.g. `vmware-monitor event_list --vm web01 --since 1h`, `vmware-log-insight log_search ...`, `vmware-aria alert_query ...`).
+2. Pass them all to **`incident_timeline`** (envelope below). Read the top hypothesis + `next_checks`.
+3. Follow `next_checks` to pull more targeted data; re-run `incident_timeline` to confirm.
+4. **Failure branch — no events come back:** the affected target may be unreachable. Run the source skill's `doctor`/health first; a 503/timeout is a *signal* (platform not ready), not a dead end.
+5. Produce a diagnosis + recommended fix. Route execution to aiops/pilot. **Do not fix here.**
+
+### 2. "I don't even know what to check"
+1. Run **`list_symptom_categories`** (or `vmware-debug categories`) to see the catalogue.
+2. Describe the symptom; map it to a category; the `suggested_check` tells you which skill/tool to run first.
+3. Collect → `incident_timeline` → narrow. Loop until one hypothesis dominates.
+
+### 3. Hand off the fix (advisor → executor, like vmware-harden)
+1. Debug emits a structured diagnosis + a proposed remediation (steps).
+2. **Single, low-risk fix** → call the matching **vmware-aiops** tool (it has its own double-confirm).
+3. **Multi-step / needs approval / cross-skill** → submit the plan to **vmware-pilot**, which owns the state machine, approval gate, rollback, and audit.
+4. **Failure branch — fix is ambiguous or risky:** stop and present the hypotheses to the user; never guess-execute.
+
+## Usage Mode
+
+- **MCP** (in an agent): the agent calls the other skills' read tools, then `incident_timeline` to correlate. This is the primary mode — that's where the cross-skill "联动" happens.
+- **CLI** (humans): `vmware-debug triage --events events.json` correlates a JSON array you collected yourself.
+
+## MCP Tools (2 — 2 read, 0 write)
+
+| Tool | What |
+|---|---|
+| `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
+| `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
+
+**Event envelope** (input to `incident_timeline`): `{ts, source, severity, entity, text, fields}`.
+See `references/event-envelope.md`. The agent normalises each source's events into this
+shape; debug stays source-agnostic and has no dependency on the other packages.
+
+## CLI Quick Reference
+
+```bash
+vmware-debug categories                        # what can it diagnose
+vmware-debug triage --events events.json       # correlate a collected event set
+cat events.json | vmware-debug triage          # or via stdin
+vmware-debug mcp                                # start stdio MCP server (proxy-safe)
+```
+
+## Troubleshooting
+
+- **`incident_timeline` raises "event[N] could not be normalised"** — event N is missing a timestamp or has an unparseable one. Every event needs `ts` (ISO-8601, epoch seconds, or millis).
+- **All hypotheses come back "uncategorized"** — the symptom isn't in the catalogue yet; widen the window and pull from another source (aria anomalies, log-insight). Consider adding a signature (see `references/routing.md`).
+- **No spikes detected on an obvious burst** — you need ≥3 time bins for a baseline; shrink `bin_seconds`.
+- **It won't execute the fix** — by design. Route to vmware-aiops or vmware-pilot.
+
+## Audit & Safety
+
+Read-only by construction: no write tools, no network, nothing executed. Remediation
+is always routed to aiops/pilot, where the double-confirm / approval / audit gates live
+(audit DB `~/.vmware/audit.db`). See `references/setup-guide.md`.
+
+## License
+
+MIT.

vmware_debug-1.6.1/skills/vmware-debug/references/capabilities.md

@@ -0,0 +1,32 @@
+# vmware-debug Capabilities
+
+Read-only, offline incident correlation. No network, no credentials, no writes.
+
+| Tool | What it returns | Typical response tokens |
+|---|---|---|
+| `incident_timeline` | `{event_count, window, spikes:[{start,end,count,zscore}], hypotheses:[{category, score, summary, evidence_count, first_seen, last_seen, sample_text, suggested_check}], next_checks:[...]}` | 300–2000 (scales with hypotheses) |
+| `list_symptom_categories` | `[{category, example_keywords, suggested_check}]` | ~400 |
+
+## Correlation engine
+
+- **Timeline**: events normalised to the unified envelope, sorted, and time-binned
+  (auto bin width ≈ span/30, or caller-specified).
+- **Spike detection**: z-score over bin counts (≥3 bins required for a baseline;
+  flat series yields no false spikes).
+- **Hypothesis ranking**: events clustered by symptom category (keyword match on
+  text + entity), scored by summed severity weight, tie-broken by recency.
+  Uncategorised events are kept visible, not dropped.
+- **Next-check routing**: each category carries a concrete "which skill/tool to run
+  next" suggestion — the value when the user doesn't know what to check.
+
+## Symptom categories
+
+`storage`, `network`, `compute`, `ha_drs`, `power_lifecycle`, `auth`, `platform`.
+See `references/routing.md` for keyword signatures and the skill each routes to.
+
+## Design properties
+
+- **Zero cross-skill runtime deps** — correlation is pure functions over plain
+  dicts; the agent fans out to other skills' read tools (踩坑 #21/#32).
+- **JSON-serialisable output** — suitable for direct MCP responses.
+- **Immutable** — inputs are never mutated; every function returns new values.

vmware_debug-1.6.1/skills/vmware-debug/references/cli-reference.md

@@ -0,0 +1,48 @@
+# vmware-debug CLI Reference
+
+All commands are read-only and offline (no network, no credentials).
+
+## triage — correlate a set of collected events
+
+```bash
+vmware-debug triage [OPTIONS]
+  -e, --events PATH     JSON file of event envelopes (reads stdin if omitted)
+      --bin-seconds N   Time-bin width (auto if omitted)
+      --top-n N         Max hypotheses to return   [default: 5]
+```
+
+Input is a JSON array of event envelopes (see `references/event-envelope.md`):
+
+```bash
+cat events.json | vmware-debug triage
+vmware-debug triage --events events.json --top-n 3
+```
+
+Output (JSON): `{event_count, window, spikes, hypotheses, next_checks}`.
+
+## categories — list recognised symptom categories
+
+```bash
+vmware-debug categories
+```
+
+Prints each category, sample keywords, and the suggested next check (which
+skill/tool to run). Use when you don't know what to look at.
+
+## version / mcp
+
+```bash
+vmware-debug version    # installed version
+vmware-debug mcp        # start the stdio MCP server (no network at startup)
+```
+
+## How the agent uses it
+
+In an agent, the cross-skill correlation happens at the agent layer:
+
+1. Fetch events with the data-source skills (vmware-monitor `event_list`,
+   vmware-log-insight `log_search`/`log_aggregate`, vmware-aria alerts/anomaly,
+   vmware-nsx).
+2. Normalise each into the event envelope.
+3. Call the `incident_timeline` MCP tool to correlate and rank.
+4. Follow `next_checks`; route any fix to vmware-aiops / vmware-pilot.

vmware_debug-1.6.1/skills/vmware-debug/references/event-envelope.md

@@ -0,0 +1,49 @@
+# The Unified Event Envelope
+
+This is the contract between `vmware-debug` and every data-source skill. The
+orchestrating agent fetches events with each skill's own read tools, normalises
+each into this shape, and passes the list to `incident_timeline`. Debug has **no
+runtime dependency** on the other packages (no version lockstep, no heavy install).
+
+## Shape
+
+```json
+{
+  "ts":       "2026-06-23T10:15:30Z",
+  "source":   "monitor",
+  "severity": "error",
+  "entity":   "vm-web01",
+  "text":     "Device naa.600... performance has deteriorated",
+  "fields":   { "host": "esxi-03", "datastore": "ds1" }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `ts` | string \| number | ISO-8601, epoch **seconds**, or epoch **millis** (auto-detected). Required. |
+| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... |
+| `severity` | string | Free text; normalised to `critical`/`error`/`warning`/`info`/`unknown`. |
+| `entity` | string | The object the event is about (VM/host/datastore). May be empty. |
+| `text` | string | Human-readable message — this is what the symptom classifier matches on. |
+| `fields` | object | Any source-specific extras; preserved, never dropped. |
+
+The normaliser is tolerant of common field-name variants (e.g. `timestamp`,
+`createTime`, `startTimeUTC` for `ts`; `criticality`, `level` for `severity`;
+`resourceName`, `vm_name`, `fullFormattedMessage` for entity/text), so most
+sources map with little or no adaptation.
+
+## Mapping cheatsheet per source
+
+| Source tool (example) | ts | severity | entity | text |
+|---|---|---|---|---|
+| vmware-monitor `event_list` | `createdTime` | `severity` | `vm`/`host` | `fullFormattedMessage` |
+| vmware-aria `alert_query` | `startTimeUTC` | `criticality` | `resourceName` | `alertDefinitionName` |
+| vmware-aria `anomaly` | `timestamp` | (derive) | `resourceName` | stat + value |
+| vmware-log-insight `log_search` | `timestamp` | `severity`/derive | `hostname` | `text` |
+| vmware-nsx (firewall/traceflow) | `time` | (derive) | src/dst | rule/verdict |
+
+## Why this design
+
+- **Decoupling** — debug never imports monitor/aria/log-insight (CLAUDE.md 踩坑 #21/#32).
+- **Testability** — correlation is pure functions over `Event`; unit tests feed synthetic events.
+- **Transparency** — the cross-skill "联动" happens at the agent layer, visibly, not hidden inside debug.