vcf-super-cli 0.2.0__tar.gz → 0.4.0__tar.gz

vcf_super_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to `vcf-super-cli` are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/), and from v1.0.0 the project
+will follow [Semantic Versioning](https://semver.org/). While on `0.x`, minor
+versions may include breaking changes.
+
+## [Unreleased]
+
+## v0.4.0 — 2026-06-08
+
+Live resource-id completion. Pressing `<TAB>` on an id-typed argument can now
+suggest **real ids** from the live inventory — strictly opt-in, cached, and
+fail-soft. The agent-facing contract is unchanged: stable JSON, error envelope,
+exit codes, dry-run-by-default writes, and `--help` stays fully offline.
+
+### Added
+
+- **Live resource-id completion** (#44), opt-in via `VSC_COMPLETE_DYNAMIC=1` and
+  off by default. When enabled, `<TAB>` on an id arg/option suggests live ids for
+  the resource type (VMs, hosts, clusters, datacenters, datastores, resource
+  pools), with each resource's name shown as completion help. Built on:
+  - a resource-type → list-op **registry** derived purely by introspecting the
+    SDK metadata (#45), no network;
+  - a **TTL cache** under the platform cache dir, keyed by
+    profile/backend/resource-type (default 60s, `VSC_COMPLETE_TTL` override) (#46);
+  - a **dynamic completer** whose fetch is time-bounded (`VSC_COMPLETE_TIMEOUT`,
+    default 2s) and blanket fail-soft — any error, missing auth, or timeout
+    yields no suggestions and is never cached (#47).
+- Static/offline completion (enums, output formats, profiles, filter enums) is
+  unchanged and remains the default. `--help` and command execution never open a
+  connection for completion.
+
+### Notes
+
+- Live completion is a human convenience only; agents should keep using `list`
+  to discover ids and must not depend on completion for correctness (#48).
+
+## v0.3.0 — 2026-06-05
+
+Ergonomics: friendlier filtering and paging, offline shell completion, and a
+pyVmomi fallback surface for gaps the REST/vAPI layer doesn't cover. The
+agent-facing contract is unchanged — stable JSON, error envelope, exit codes,
+and writes still dry-run by default.
+
+### Added
+
+- **Static shell completion** (#32), fully offline — never opens a connection.
+  Completes enum option choices, output formats, configured profile names, and
+  `list` filter enum values. Install with `vsc --install-completion`. (Live
+  resource-id completion is intentionally deferred to a later release.)
+- **Per-field filter flags** (#33). `list` commands flatten the SDK filter spec
+  into typed `--<field>` options (repeatable for list/set fields; enum choices
+  validated and completed), e.g. `vsc vsphere vm list --power-states POWERED_ON
+  --names web-1`. The raw `--filter '<json>'` blob stays as a base layer that
+  per-field flags override.
+- **Pagination helpers** (#33): `--all` follows the NSX cursor across pages;
+  `--max-items N` caps the total; `--limit N` is a client-side cap for
+  non-paginated (vSphere) lists. Without `--all`, a paginated `list` returns one
+  page and surfaces its `cursor` for manual paging.
+- **pyVmomi fallback commands** (read-only) under `vsc vsphere`, for areas the
+  REST/vAPI surface lacks — same JSON / error-envelope / exit-code contract:
+  - `perf vm|host --metric <group.name>` — performance counters via the
+    PerformanceManager (#34).
+  - `events list [--vm|--host] [--since 1h]` and `tasks list` — recent events
+    and recent/running tasks (#35).
+  - `inventory vm|host [--props <path>]…` — a PropertyCollector property walk
+    (#36).
+
+### Changed
+
+- Documentation and the bundled agent `SKILL.md` describe completion, the filter
+  and paging flags, and the pyVmomi fallback surface.
+
+## v0.2.0 — 2026-06-05
+
+First PyPI release. Adds the **write** surface on top of the v0.1 read-only
+foundation, with a dry-run-by-default safety model.
+
+### Added
+
+- **Write operations** (`POST`/`PUT`/`PATCH`/`DELETE`) are generated from the
+  `vcf-sdk` vAPI metadata alongside reads (#20). Clean, collision-free verbs:
+  `POST ?action=X` → `X`; otherwise `PUT` → `set`, `PATCH` → `patch`,
+  `DELETE` → `delete` (force variants prefixed `force-`); `POST` without an
+  action keeps its operation id.
+- **Dry-run by default + `--apply`** (#21). Every write previews the resolved
+  request and changes nothing — and opens **no connection** — unless `--apply`
+  is passed. `--apply` is the only gate (no interactive prompt), so the CLI
+  stays fully scriptable. New `vsc/gen/preview.py` builds the request plan.
+- **Stable write envelope**, identical across modes — branch on `applied`:
+  - dry-run: `{ "applied": false, "request": { method, url, path_params, query, body, … }, "apply_hint": … }`
+  - applied: `{ "applied": true, "request": { … }, "result": <sdk response> }`
+- **Body/spec construction from JSON** for both conventions: NSX's named request
+  body and vCenter's spec parameters, built into the SDK binding structs.
+- **Catalog expansion**: vSphere `resource-pool` and the VM power/hardware leaves
+  (`power`, `cpu`, `memory`, `disk`, `ethernet`); NSX `ip-pools`,
+  `dhcp-server-configs`, `dhcp-relay-configs`, and Tier-1 `locale-services`.
+- **`CONFLICT` (7) / `UNAVAILABLE` (8)** exit-code coverage for write errors
+  (#22), derived from the error-type map so it can't drift.
+
+### Changed
+
+- A malformed or incomplete write body is reported during the dry-run as the
+  structured usage envelope (exit `2`) — before any connection — not as a
+  traceback.
+- Documentation and the bundled agent `SKILL.md` describe the write surface and
+  the `--apply` safety model (#23).
+
+## v0.1.0 — 2026-06-05
+
+Initial read-only foundation (not published to PyPI).
+
+### Added
+
+- Command tree **generated dynamically** by introspecting the installed `vcf-sdk`
+  vAPI bindings (`VapiInterface` services + `OperationRestMetadata`), fully
+  offline — `--help` works without a server or credentials.
+- Read (`GET`) commands for vSphere/vCenter (`vsc vsphere …`) and NSX Policy
+  (`vsc nsx …`), split into two product groups.
+- Named **profiles** with env-var overrides and optional OS-keyring secret
+  storage; `--profile/-p` selection.
+- **Output contract**: JSON by default, `--output table` for humans; a stable
+  error envelope on stderr and documented, frozen **exit codes**.
+- Bundled agent **Skill** shipped in the wheel, exportable via `vsc skill export`.

{vcf_super_cli-0.2.0 → vcf_super_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Modern, agent-friendly CLI for VMware Cloud Foundation 9, with a command tree generated dynamically from the vcf-sdk vAPI bindings.
 Project-URL: Homepage, https://github.com/thomaschristory/vcf-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/vcf-super-cli/
@@ -73,7 +73,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | vSphere / vCenter read (`vsc vsphere …`) | ✅ v0.1 |
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
-| Dynamic shell completion, per-field filter flags, pyVmomi fallback | v0.3 (planned) |
+| Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
+| Live resource-id completion | planned |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.2.0 → vcf_super_cli-0.4.0}/README.md

@@ -41,7 +41,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | vSphere / vCenter read (`vsc vsphere …`) | ✅ v0.1 |
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
-| Dynamic shell completion, per-field filter flags, pyVmomi fallback | v0.3 (planned) |
+| Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
+| Live resource-id completion | planned |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

vcf_super_cli-0.4.0/docs/commands.md

@@ -0,0 +1,112 @@
+# Commands
+
+The `vsphere` and `nsx` command trees are **generated from the `vcf-sdk` vAPI
+bindings**, so `vsc --help` (and each sub-`--help`) is always the authoritative,
+version-accurate reference. This page is an overview.
+
+Generated leaves expose both **read** and **write** verbs:
+
+- `list` — list resources (optional `--filter '<json>'`)
+- `get <id>` — fetch one resource by id, **where the SDK provides a by-id GET**
+  (e.g. `vm`, `cluster`, `datacenter`, `datastore`; some leaves such as `host`,
+  `folder`, and `network` are `list`-only)
+- writes — `create`, `delete`, `set` (PUT upsert), `patch`, and action verbs
+  (e.g. `start`/`stop`/`reset` under `power`). **Writes are dry-run by default and
+  require `--apply`** — see [Writes](writes.md).
+
+## `vsc vsphere …` (vCenter)
+
+Generated from `com.vmware.vcenter`:
+
+| Group | Examples |
+|-------|----------|
+| `vm` | `vsc vsphere vm list`, `vsc vsphere vm get <vm>`, `vsc vsphere vm delete <vm> --apply` |
+| `host` | `vsc vsphere host list`, `vsc vsphere host disconnect <host> --apply` |
+| `cluster` | `vsc vsphere cluster list` |
+| `datacenter` | `vsc vsphere datacenter list` |
+| `datastore` | `vsc vsphere datastore list` |
+| `folder` | `vsc vsphere folder list` |
+| `network` | `vsc vsphere network list` |
+| `resource-pool` | `vsc vsphere resource-pool create --spec '<json>' --apply` |
+| `power` | `vsc vsphere power start\|stop\|reset\|suspend <vm> --apply` |
+| `cpu` / `memory` / `disk` / `ethernet` | VM hardware reads + writes, e.g. `vsc vsphere cpu update <vm> --spec '<json>' --apply` |
+| `perf` / `events` / `tasks` / `inventory` | **pyVmomi fallback** (read-only) — perf counters, recent events, recent/running tasks, and a property walk the REST/vAPI surface lacks (see below) |
+
+### pyVmomi fallback commands
+
+A few inventory/performance areas are only reachable over the older pyVmomi SOAP
+API. Those commands live under `vsc vsphere` alongside the generated ones, are
+**read-only** (no `--apply`), and emit the same JSON / error envelope / exit codes.
+
+- `vsc vsphere perf vm <vm> [--metric group.name]… [--max-samples N]` — performance
+  counters via the PerformanceManager. Metrics are `group.name` (e.g. `cpu.usage`)
+  or `group.name.rollup` (e.g. `cpu.usage.average`); repeat `--metric` for several.
+- `vsc vsphere perf host <host> …` — the same for an ESXi host.
+- `vsc vsphere events list [--vm <vm> | --host <host>] [--since 1h] [--max-count N]`
+  — recent events via the EventManager. `--since` takes a duration (`30s`/`15m`/
+  `2h`/`1d`); scope to at most one entity.
+- `vsc vsphere tasks list [--max-count N]` — recent and running tasks via the
+  TaskManager.
+- `vsc vsphere inventory vm <vm> [--props path]…` / `inventory host <host> …` —
+  managed-object properties the REST list ops omit (device tree, custom attributes),
+  via the PropertyCollector. `--props` is repeatable (e.g. `--props config.hardware`);
+  with none, a small per-type summary set is returned.
+
+## `vsc nsx …` (NSX Policy)
+
+Generated from `vcf.nsx.policy`:
+
+| Group | Examples |
+|-------|----------|
+| `segments` | `vsc nsx segments list`, `vsc nsx segments set <id> --segment '<json>' --apply` |
+| `tier0s` / `tier1s` | `vsc nsx tier1s list`, `vsc nsx tier1s set <id> --tier1 '<json>' --apply` |
+| `services` | `vsc nsx services list` |
+| `groups` | `vsc nsx groups list`, `vsc nsx groups delete <domain> <group> --apply` |
+| `security-policies` | `vsc nsx security-policies list` |
+| `gateway-policies` | `vsc nsx gateway-policies list` |
+| `ip-pools` | `vsc nsx ip-pools set <id> --ip-address-pool '<json>' --apply` |
+| `dhcp-server-configs` / `dhcp-relay-configs` | DHCP config reads + writes |
+| `locale-services` | Tier-1 locale services reads + writes |
+
+## Curated commands
+
+- `vsc profiles …` — manage connection profiles (see [Profiles](profiles.md))
+- `vsc skill export <dir> [--apply]` — export the bundled agent Skill
+- `vsc --version`
+
+## Filtering
+
+`list` commands expose each field of the SDK filter spec as its own typed flag.
+List-valued fields are repeatable; enum fields validate their choices and
+tab-complete:
+
+```sh
+vsc --profile prod vsphere vm list --power-states POWERED_ON --names web-1 --names web-2
+```
+
+The raw JSON spec is still accepted as a base layer / escape hatch; per-field
+flags merge **over** it (a flag wins over the same key in the blob):
+
+```sh
+vsc --profile prod vsphere vm list --filter '{"clusters": ["domain-c1"]}' --power-states POWERED_ON
+```
+
+## Pagination
+
+`list` commands accept paging flags:
+
+| Flag | Effect |
+|------|--------|
+| `--all` | follow the cursor and return **every** page (paginated backends, e.g. NSX) |
+| `--max-items N` | cap the total number of items returned |
+| `--limit N` | client-side cap for non-paginated (vSphere) lists |
+
+```sh
+vsc --profile prod nsx segments list --all            # every page, concatenated
+vsc --profile prod nsx segments list --page-size 50   # one page (cursor surfaced for manual paging)
+vsc --profile prod vsphere vm list --limit 20         # first 20 only
+```
+
+Without `--all`, a paginated `list` returns one page and surfaces the `cursor` so
+an agent can drive pagination itself. On non-paginated backends (vSphere) `--all`
+is a no-op — the output stays a plain array.

vcf_super_cli-0.4.0/docs/design.md

@@ -0,0 +1,89 @@
+# Design
+
+`vsc` builds its command tree by **statically introspecting the installed
+`vcf-sdk` vAPI bindings**. Both `vmware-vcenter` and `vcf-nsx` are vAPI stub
+libraries on the shared `vmware-vapi-runtime`:
+
+- Each service is a `VapiInterface` subclass (`VM`, `Host`, `Cluster`,
+  `Datastore`, `Network`, …).
+- Every operation carries `OperationRestMetadata` (`http_method`,
+  `path_variables`, `query_parameters`).
+- Parameters are typed via `StructType` binding types.
+
+A single generator walks those classes and emits one Typer command per
+operation. `http_method == "GET"` ⇒ a read command; other verbs ⇒ writes
+(dry-run by default + `--apply`). Because the metadata ships inside the SDK, the
+tree builds **offline** — no server needed to render `--help`.
+
+Top-level grouping:
+
+- `vsc vsphere …` → `com.vmware.vcenter` (+ selected `com.vmware.esx`)
+- `vsc nsx …` → `vcf.nsx.policy` (NSX Policy API)
+
+The introspected intermediate representation is a list of `Operation` objects,
+each carrying typed `Param`s (`vsc/gen/model.py`). Everything below is built from
+that one model.
+
+## Ergonomics (v0.3)
+
+These build on the introspected `Param` model without changing the agent
+contract.
+
+### Offline shell completion
+
+Completion values come entirely from the model and local config — **never a
+network call**, so `<TAB>` stays fast and `--help` stays offline. Enum options
+complete from their fixed choices, `--output` from the output formats, and
+`--profile` from configured profile names (`vsc/gen/complete.py`). Completing a
+live resource id would require a connection and is deferred to a later release.
+
+### Per-field filter flags
+
+A `list` operation takes a single `filter` parameter that is a struct
+(`VM.FilterSpec` etc.). The generator flattens that struct into typed
+`--<field>` options (repeatable for list/set fields; enum fields validate and
+complete their choices). The raw `--filter '<json>'` blob remains as a base
+layer that per-field flags merge **over** (`vsc/gen/filters.py`).
+
+### Pagination
+
+`list` commands gain `--all` (follow the NSX cursor across pages), `--max-items`
+(cap the total), and `--limit` (client-side cap for non-paginated vSphere
+lists). Without `--all`, a paginated list returns one page and surfaces its
+`cursor` for manual paging; on non-cursor backends `--all` is a no-op and the
+output stays a plain array (`vsc/gen/paginate.py`).
+
+## pyVmomi fallback (v0.3)
+
+A few inventory/performance areas are only reachable through the older pyVmomi
+SOAP API. Those are **hand-written read-only commands** mounted under
+`vsc vsphere` alongside the generated ones, sharing the same output contract:
+
+- a separate connection path, `connect_vmomi()` via `SmartConnect`, reusing the
+  resolved vSphere credentials and honouring `--insecure` like the REST path
+  (`vsc/connect/vmomi.py`);
+- `vmomi_jsonable()` collapses managed objects to their moref and data objects to
+  dicts so results render like any other;
+- a shared `run_read()` runner maps pyVmomi faults onto the same error envelope
+  and exit codes (`vsc/pyvmomi/runner.py`).
+
+Commands: `perf` (PerformanceManager counters), `events` / `tasks`
+(Event/Task managers), and `inventory` (a PropertyCollector property walk). All
+are reads — no `--apply`.
+
+## Design specs
+
+The authoritative, milestone-by-milestone designs live in the repository:
+
+- [v0.1 — dynamic read-only CLI](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-design.md)
+- [v0.2 — writes](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.2-writes-design.md)
+- [v0.3 — ergonomics](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.3-ergonomics-design.md)
+
+## Contracts
+
+- **Output:** JSON by default; `--output table` for humans.
+- **Errors:** stable envelope `{ "error": { code, message, kind, details } }`.
+- **Exit codes:** documented `IntEnum` (`0` ok, `1` generic, `2` usage, `3` auth,
+  `4` not-found, `5` connection, `6` config, `7` conflict, `8` unavailable).
+- **Writes:** dry-run by default; `--apply` is the only gate and a dry-run opens
+  no connection.

vcf_super_cli-0.4.0/docs/index.md

@@ -0,0 +1,46 @@
+# vcf-super-cli
+
+A modern, agent-friendly CLI for **VMware Cloud Foundation 9** whose command tree
+is **generated dynamically** from the official [`vcf-sdk`](https://pypi.org/project/vcf-sdk/)
+vAPI bindings.
+
+```console
+$ vsc vsphere vm list --power-states POWERED_ON --profile prod
+$ vsc nsx segments list --all --output table
+$ vsc vsphere perf vm vm-42 --metric cpu.usage
+```
+
+!!! warning "Pre-1.0"
+    Reads and writes are both available. **Writes are dry-run by default** —
+    nothing changes without `--apply`. See [Writes](writes.md). While on `0.x`,
+    minor versions may include breaking changes.
+
+## Highlights
+
+- **Mirrors the real API** — commands come from the SDK's vAPI metadata, covering
+  vCenter and NSX from one generator.
+- **Ergonomic** — offline tab-completion (enums, formats, profiles, filter
+  choices), per-field `--<field>` filter flags, and paging (`--all` /
+  `--max-items` / `--limit`).
+- **pyVmomi fallback** — read-only `perf`, `events`, `tasks`, and `inventory`
+  commands for areas the REST/vAPI surface doesn't cover.
+- **Safe by default** — writes are dry-run unless `--apply`; a dry-run never connects.
+- **Agent-friendly** — JSON output, stable error envelope, documented exit codes,
+  bundled agent Skill.
+
+See the [Design](design.md) for how dynamic generation works, and
+[Commands](commands.md) for the full surface.
+
+## Install
+
+```sh
+uv tool install vcf-super-cli       # or: pip install vcf-super-cli
+vsc --install-completion            # optional: offline shell completion
+```
+
+From source:
+
+```sh
+uv sync
+uv run vsc --help
+```

vcf_super_cli-0.4.0/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.3-ergonomics-design.md

@@ -0,0 +1,232 @@
+# vcf-super-cli v0.3 — Ergonomics (design)
+
+**Status:** approved 2026-06-05. Milestone: `v0.3 — ergonomics` (#3).
+**Predecessors:** [v0.1 design](2026-06-05-vcf-super-cli-design.md), [v0.2 writes design](2026-06-05-vcf-super-cli-v0.2-writes-design.md).
+
+## Goal
+
+Make the dynamically-generated CLI pleasant to drive by hand and still trivially
+scriptable by an agent. Three independent feature areas, each shipped as its own
+issue/PR under milestone #3:
+
+1. **Static shell completion** — offline tab-completion of enums, output formats,
+   profile names, and per-field filter choices.
+2. **Filter & pagination helpers** — per-field filter flags (augmenting today's
+   `--filter '<json>'` blob) and friendlier paging (`--all`, `--max-items`,
+   `--limit`).
+3. **pyVmomi fallback commands** — hand-written read commands (perf, events/tasks,
+   inventory walk) for gaps the vAPI/REST surface doesn't cover.
+
+The agent contract is unchanged and non-negotiable: stable JSON output, the
+documented error envelope, the frozen exit codes, and **writes stay dry-run by
+default**. The pyVmomi additions are all reads, so they need no `--apply` gate.
+
+## Locked decisions (from brainstorm, 2026-06-05)
+
+- **Completion is static/offline only.** No feature in v0.3 hits the API during
+  `<TAB>`. Live resource-ID completion (e.g. completing `<vm>` from a live list)
+  is explicitly **deferred to v0.4**; the param model already carries
+  `resource_types` so it remains a clean future extension.
+- **Filter flags augment, never replace, `--filter`.** Raw `--filter '<json>'`
+  stays as the base layer / escape hatch; generated per-field flags merge over it.
+- **Pagination:** `--all` auto-follows the NSX cursor; `--max-items` caps total;
+  `--limit` is a client-side cap for non-cursor (vSphere) lists. NSX
+  `--page-size`/`--cursor` already exist as generated query options.
+- **pyVmomi covers all three families** (perf, events/tasks, inventory walk),
+  built on a small shared `SmartConnect` foundation.
+
+---
+
+## Feature 1 — Static shell completion
+
+### Behaviour
+
+Completion values are derived entirely from the introspected `Param` model plus
+local config — never from a network call. `--help` and completion both stay fully
+offline.
+
+Completed surfaces:
+
+| Surface | Source | Example |
+|---------|--------|---------|
+| enum option | `param.enum_values` | `--power-state POWERED_<TAB>` → `POWERED_ON`, `POWERED_OFF` |
+| `--output` / `-o` | `OutputFormat` members | `-o <TAB>` → `json`, `table` |
+| global `--profile` / `-p` | profile names from `load_config()` (offline file read) | `-p <TAB>` → `prod`, `lab` |
+| per-field filter enum flags | reuse enum completer (feature 2) | `--filter-power-state <TAB>` |
+
+Resource-ID args (the `<vm>` positionals) are **not** completed in v0.3.
+
+### Implementation
+
+- New module **`vsc/gen/complete.py`** — pure completer factories:
+  - `enum_completer(values: list[str]) -> Callable[[str], list[str]]`
+  - `profile_completer() -> Callable[[str], list[str]]`
+  Each takes the Click `incomplete` string and returns the prefix-filtered
+  candidate list. No `ctx`/`param` dependency → unit-testable without a shell.
+- **`vsc/gen/builder.py`** `_build_signature`: when a non-path option is built for
+  an `ENUM` param, pass `autocompletion=enum_completer(param.enum_values)` to
+  `typer.Option`. When building `--output`, attach an `OutputFormat` completer.
+- **`vsc/cli/app.py`** main callback: attach `profile_completer()` to `--profile`.
+- Root app already sets `add_completion=True`; document `vsc --install-completion`
+  and `vsc --show-completion` in `docs/usage.md`.
+
+### Tests
+
+`tests/test_complete.py` — completer factories return correctly prefix-filtered
+lists, empty `incomplete` returns all, no match returns `[]`. A smoke test asserts
+generated enum options carry an `autocompletion` callback.
+
+---
+
+## Feature 2 — Filter & pagination helpers
+
+### Per-field filter flags
+
+vCenter list operations take a single `filter` parameter that is a `STRUCT`
+(`VM.FilterSpec` etc.). Today the user must pass it as `--filter '<json>'`. v0.3
+additionally flattens that struct's fields into typed options.
+
+- **Detection:** on a read/list op, a parameter that is `ParamKind.STRUCT` **and
+  named `filter`** is flattened. Write-body structs are *not* flattened — they
+  stay JSON (`--spec`, `--segment`, …).
+- **Generated flags:** each struct field → `--<field>` (kebab-cased). `list`/`set`
+  fields are **repeatable** (`list[str]` annotation, multiple uses accumulate).
+  `enum` fields carry choices in help + the enum completer.
+- **Precedence / merge:** raw `--filter '<json>'` provides the base dict; per-field
+  flags merge **over** it (a flag wins over the same key in the blob). The merged
+  dict is coerced into the FilterSpec via the existing
+  `coerce_struct`/`coerce_value` path — no new coercion logic.
+- **Collisions:** a flattened field whose flag would collide with a reserved option
+  (`--output`, `--apply`) or another option is suffixed using the existing
+  `_sig_name` mechanism.
+
+New helper **`vsc/gen/filters.py`**:
+- `flatten_filter(param: Param) -> list[Param]` — child params for each struct field
+  (built with `param_from_type` on `struct_type.get_field(name)`).
+- `assemble_filter(base_json, field_values, param) -> Any` — merge base + per-field
+  values and coerce into the struct. Pure; unit-testable.
+
+`builder.py` consumes these: `_build_signature` emits the child options (tracking
+them so `_collect_kwargs` knows to reassemble rather than pass them through), and
+`_collect_kwargs` calls `assemble_filter` to rebuild the single `filter` kwarg.
+
+### Pagination
+
+NSX Policy list ops return a `*ListResult` struct (`.results`, `.cursor`,
+`.result_count`) and already expose `cursor`/`page_size` as generated query
+options. vSphere REST list ops return a plain list and do not paginate.
+
+Injected options on **list verbs** (`op.cli_verb == "list"`):
+
+| Flag | Applies to | Effect |
+|------|-----------|--------|
+| `--all` | cursor lists (NSX) | follow `.cursor` across pages, concatenate `.results`, stop at `--max-items` |
+| `--max-items N` | all lists | hard cap on returned items (post-fetch for vSphere, loop-stop for `--all`) |
+| `--limit N` | non-cursor lists (vSphere) | client-side slice of the returned list |
+
+Without `--all`, a cursor list returns one page **including** its `cursor`, so an
+agent can paginate manually. `--all` and `--max-items` interact: the follow loop
+stops once `--max-items` items are collected.
+
+New helper **`vsc/gen/paginate.py`**:
+- `follow_cursor(fetch_page, *, max_items) -> list` — `fetch_page(cursor) ->
+  (results, next_cursor)`; loops until `next_cursor` is empty/repeated or the cap
+  is hit. Pure given the `fetch_page` callable (the callable closes over the SDK
+  method in `builder.py`); unit-testable with a fake pager.
+
+`builder.py` `make_command` detects a cursor-bearing result and, when `--all` is
+set, drives `follow_cursor`; otherwise applies `--limit`/`--max-items` slicing
+before `emit()`.
+
+### Tests
+
+`tests/test_filters.py` — flatten produces one child per field with correct
+kind/required/repeatable; assemble merges blob + flags with flags winning; enum
+field carries choices. `tests/test_paginate.py` — `follow_cursor` concatenates,
+respects `max_items`, terminates on empty/duplicate cursor. Builder integration
+tests assert a vCenter list op grows `--<field>` options and an NSX list op grows
+`--all`/`--max-items`.
+
+---
+
+## Feature 3 — pyVmomi fallback commands
+
+Hand-written read commands for gaps the vAPI/REST surface doesn't cover, mounted
+into the existing `vsc vsphere` tree and emitted through the existing
+`emit()`/error-envelope contract.
+
+### Foundation
+
+- New module **`vsc/connect/vmomi.py`**:
+  - `connect_vmomi() -> ServiceInstance` via `pyVim.connect.SmartConnect`, reusing
+    `resolve_target("vsphere")` for server/user/password and an `ssl` context that
+    honours `verify` (unverified context when `insecure`). Cached like the vAPI
+    connections (`reset_cache()` clears it); `Disconnect` registered at process
+    exit.
+  - `vmomi_jsonable(obj) -> Any` — convert managed-object / data-object trees into
+    plain JSON-able dicts (`moref` → `{"type", "value"}`, data objects → field
+    dicts, leave scalars/datetimes alone) so `emit()` renders them like any other
+    result.
+- New package **`vsc/pyvmomi/`**, one module per family, each exposing a
+  `typer.Typer`. `vsc/cli/app.py` adds them onto the vsphere group
+  (`vsphere_group.add_typer(perf_app, name="perf")`, …). pyVmomi errors
+  (`vim.fault.*`, connection failures) map into the existing envelope/exit codes
+  (auth→3, not-found→4, connection→5) via a small adapter reusing
+  `vsc/output/errors.py` patterns.
+
+### Commands
+
+- **`vsc vsphere perf`** — real-time/historical counters via `PerformanceManager`.
+  e.g. `perf vm <vm> --metric cpu.usage [--interval 20s]`,
+  `perf host <host> --metric mem.usage`. Resolves the counter id, queries
+  `QueryPerf`, emits timestamped samples.
+- **`vsc vsphere events`** — recent events via `EventManager` with `--since`/entity
+  filters. **`vsc vsphere tasks`** — running + recent tasks via `TaskManager`.
+- **`vsc vsphere inventory`** — `PropertyCollector` walk for properties the REST
+  list ops omit (device tree, custom attributes, relationships), e.g.
+  `inventory vm <vm> --props config.hardware`.
+
+All are reads → no `--apply`. They accept the same `--output json|table` and obey
+`--profile`.
+
+### Tests
+
+pyVmomi has no offline-introspection trick like the vAPI bindings, so tests mock
+`SmartConnect`/`ServiceInstance` and the relevant managers. `tests/test_vmomi.py`
+covers `vmomi_jsonable` conversion (moref/data-object/scalar) purely;
+`tests/test_pyvmomi_*.py` drive each command against a fake `ServiceInstance`
+asserting the emitted JSON shape and error mapping. No live vCenter required.
+
+---
+
+## Cross-cutting
+
+- Each feature PR updates the relevant `docs/` page(s) and the bundled
+  `vsc/skill/assets/SKILL.md` for any new surface.
+- `ruff`, `mypy --strict`, `pytest`, and `mkdocs --strict` stay green; CI green
+  before merge.
+- Every PR gets an adversarial **refute-before-accept** review pass; findings are
+  fixed before merge.
+
+## Issues (milestone #3)
+
+| Issue | Title | Depends on |
+|-------|-------|-----------|
+| Epic | v0.3 — ergonomics | — |
+| A | Static shell completion (enums, `--output`, `--profile`, filter choices) | — |
+| B | Filter & pagination helpers (per-field flags + `--all`/`--max-items`/`--limit`) | — |
+| C | pyVmomi fallback foundation + `vsc vsphere perf` | — |
+| D | pyVmomi events & tasks | C |
+| E | pyVmomi inventory walk | C |
+| F | v0.3 docs/SKILL roundup + release prep | A–E |
+
+Build order: A and B in parallel; C → (D, E); F last. The release tag (`vX.Y.Z`)
+is pushed **manually by the maintainer** after F merges — `release.yml` keeps **no
+`environment:` block** (the PyPI trusted publisher is registered with a blank
+environment; they must stay matched).
+
+## Out of scope (v0.3)
+
+- Live resource-ID completion (hits the API) — v0.4 candidate.
+- pyVmomi *writes* — the fallback surface is read-only this milestone.
+- NSX Manager / Global-Manager APIs (still Policy-only).