pvectl 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb04ff3ee9a4e695997d9d9ca6f5916739192462b99613e958e7688b8d12c35a
+  data.tar.gz: f896c8bed260817c0f4cdb92fded47564d936b305b26bba23cf3521c5e8383d9
+SHA512:
+  metadata.gz: 3dab5c1c7042461e7077b2ff21046c8d3d47a23a06c89cf1d456406355aa6d9f95a6773bb02f662b79d24fc824c46beec7cc1eea269076e8151cb8563628e88e
+  data.tar.gz: d30437f002bfa2c551ef384325ab92af5a92f859036976ba8c9557d70069fba2febd2ef75f684c25300fc83018c6a584002a26031ccfda9027d15ed81dfb544d

data/.claude/rules/branch-before-changes.md

@@ -0,0 +1,52 @@
+# Branch Before Changes Rule
+
+## MUST work on a feature branch before modifying any repository files
+
+Every time you need to modify files in the repository, you MUST follow this sequence:
+
+```
+1. Be on a feature branch  →  2. Make changes  →  3. Commit  →  STOP
+```
+
+**Workflow ends at commit.** The agent must NOT push and must NOT create a pull request on its own initiative. Push and PR creation require an explicit user request — see `git-workflow.md` for details.
+
+### Workflow
+
+```bash
+# 1. Determine the working branch
+#    - If already on a non-main feature branch: continue using it (preferred)
+#    - If on main: create a new feature branch
+git status                              # check current branch
+git checkout -b <type>/<short-description> main   # only if on main
+
+# 2. Make changes, commit (see git-workflow.md for commit conventions)
+git add <files>
+git commit -m "<type>(<scope>): <description>"
+
+# 3. STOP. Do NOT push or create PRs on your own — these need explicit user request.
+#    git merge is allowed for local integration when appropriate.
+```
+
+### Rules
+
+- **NEVER commit changes directly to `main`** — always work on a feature branch.
+- **NEVER push to remote on agent initiative** — `git push` only when the user explicitly asks for it.
+- **NEVER create pull requests on agent initiative** — `gh pr create` only when the user explicitly asks for it.
+- `git merge` is allowed for local merges between branches.
+- If currently on a non-`main` branch, **continue working there** — do not create a new branch unless the new request is clearly a different scope.
+- Create a new branch **before** making any file modifications, not after.
+- One logical *initiative* per branch — multiple commits per branch is expected and desired.
+- If the user asks to make a change without specifying a branch and we're on `main`, create one automatically following `git-workflow.md` naming conventions.
+- After committing, stay on the feature branch.
+
+### When this applies
+
+- Any code changes (`lib/`, `test/`, `sig/`)
+- Configuration changes (`.claude/rules/`, `CLAUDE.md`, `.mcp.json`)
+- Documentation changes (`CHANGELOG.md`, `README.md`)
+- Any other tracked file in the repository
+
+### When this does NOT apply
+
+- Read-only operations (exploring code, running tests, searching)
+- Changes to files outside the repository (memory files, local config)

data/.claude/rules/documentation-updates.md

@@ -0,0 +1,104 @@
+# Documentation Update Rules
+
+## CLAUDE.md philosophy
+
+CLAUDE.md defines **architectural assumptions and conventions** — how to build, not what exists. It should contain:
+- Design patterns and when to use them
+- Architectural flow diagrams (data paths, layer responsibilities)
+- Module layer roles (directory → purpose mapping)
+- Coding conventions and style rules
+- Configuration format and loading hierarchy
+- Known pitfalls and anti-patterns
+
+It must NOT contain:
+- Class/module inventories or lists of files
+- Specific class names beyond pattern examples (e.g., "BaseTemplate" in Hybrid Include is fine, but listing all 12 repositories is not)
+- Feature lists or command enumerations (that belongs in README)
+- Anything that requires updating when adding a new class within an existing pattern
+
+**Litmus test:** If adding a new handler/model/presenter/repository requires editing CLAUDE.md, the document has drifted into inventory territory.
+
+## MUST update documentation after completing changes
+
+After finishing any feature, bugfix, refactor, or other code change — before claiming work is done — you MUST update:
+
+### 1. CHANGELOG.md
+
+- Add entry under `## [Unreleased]` in the appropriate section:
+  - **Added** — new features and capabilities
+  - **Changed** — changes to existing functionality
+  - **Fixed** — bug fixes
+  - **Removed** — removed features
+  - **Documentation** — documentation-only changes
+- Format: `- **scope**: Description of what changed`
+- Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) conventions
+- All entries in English (matching project convention: code, comments, commits in English)
+
+### 2. README.md
+
+- Update if the change affects user-facing behavior:
+  - New commands or subcommands
+  - New flags or options
+  - Changed CLI syntax or output
+  - New configuration options
+  - New features described in the Features section
+- Do NOT update README for internal refactors, test changes, or implementation details invisible to the user
+
+### 3. CLI Help (`long_desc`)
+
+When adding or modifying a command, MUST update its `long_desc` help text:
+
+- Every command MUST have a `long_desc` with man-page style sections: DESCRIPTION, EXAMPLES, NOTES, SEE ALSO
+- Sub-commands use `parent.long_desc <<~HELP ... HELP` BEFORE `parent.command :name do |s|` (NOT `s.long_desc` inside the block — GLI ignores it)
+- Sub-commands also need `parent.desc "..."` before `parent.command` for the short description
+- Include 2-5 practical examples with `$ pvectl ...` syntax
+- Reference related commands in SEE ALSO
+
+### 4. GitHub Wiki
+
+When changes affect user-facing behavior, update the relevant wiki page(s):
+
+- Wiki repo is cloned locally (see `CLAUDE.local.md` for path)
+- Key pages to consider: Command-Reference.md, Configuration-Guide.md, Getting-Started.md, Workflows.md
+- New commands → update Command-Reference.md
+- New flags/options → update Command-Reference.md and any relevant guide pages
+- New configuration options → update Configuration-Guide.md
+- Commit and push wiki changes separately (wiki is a separate git repo)
+
+### When to skip
+
+- Pure test changes (`test:` commits) — skip README/wiki, add to CHANGELOG only if significant
+- CI/CD or tooling changes (`chore:` commits) — skip all unless user-facing
+- `.claude/` config changes — skip all
+
+### 3. CLAUDE.md — propose only, do NOT auto-update
+
+After completing work, evaluate whether the change affects project architecture or conventions documented in CLAUDE.md. If it does, **propose the update to the user** — do NOT modify CLAUDE.md automatically.
+
+Propose when:
+- A new architectural pattern or convention was introduced
+- An existing pattern described in CLAUDE.md was changed or removed
+- A new module layer was added (new directory under `lib/pvectl/`)
+- Design patterns table needs a new entry
+
+Do NOT propose for:
+- Adding new classes/files within existing patterns (new handler, new model, etc.)
+- Bug fixes, refactors that don't change architecture
+- Anything that would turn CLAUDE.md into a class inventory
+
+Format: briefly describe what changed and suggest specific edits. Wait for user approval before touching CLAUDE.md.
+
+### Order of operations
+
+```
+1. Implement changes
+2. Update RBS signatures (see rbs-signatures.md)
+3. Update CLI help long_desc (if command changed)
+4. Verify (tests pass, rbs parse clean)
+5. Update CHANGELOG.md
+6. Update README.md (if user-facing)
+7. Update GitHub Wiki (if user-facing)
+8. Propose CLAUDE.md update (if architecture changed)
+9. Commit code changes
+10. Commit and push wiki changes (separate repo)
+```

data/.claude/rules/git-workflow.md

@@ -0,0 +1,84 @@
+# Git Workflow Rules
+
+## Branch Strategy
+
+This project uses simple feature branches — NO git worktrees.
+
+### Branch Naming
+
+Use descriptive branch names with prefixes matching Conventional Commits:
+
+| Prefix | Use Case | Example |
+|--------|----------|---------|
+| `feat/` | New features | `feat/describe-command` |
+| `fix/` | Bug fixes | `fix/get-params-encoding` |
+| `refactor/` | Code restructuring | `refactor/repository-pattern` |
+| `test/` | Test improvements | `test/mock-coverage` |
+| `docs/` | Documentation | `docs/rdoc-annotations` |
+| `chore/` | Tooling, deps, config | `chore/update-dependencies` |
+
+### Branch Lifecycle
+
+1. **Start** — determine the working branch:
+   - If currently on a non-`main` branch, **continue using it** (append commits to the ongoing branch). This is the default to avoid branch proliferation.
+   - If on `main`, create a new feature branch:
+     ```bash
+     git checkout -b feat/my-feature main
+     ```
+   - Only create a new branch from `main` if the new work is a clearly different scope from the current branch.
+
+2. **Commit** frequently with small, atomic commits (see Commit Rules below).
+
+3. **Stop** — the agent's workflow ends at the commit. **DO NOT push and DO NOT create a PR on your own initiative.** Pushing and PR creation require an explicit user request.
+
+### Rules
+
+- **NEVER push to remote on agent initiative** — `git push`, `git push -u`, force-push, any variant. Push is permitted ONLY when the user explicitly asks for it (e.g. "push it", "wypchnij branch"). The agent must NOT decide on its own that the work is "ready to push" or push as part of a workflow.
+- **NEVER create pull requests on agent initiative** — `gh pr create` and any equivalent (web UI automation, API calls, scripts) is permitted ONLY when the user explicitly asks (e.g. "open a PR", "stwórz PR"). The agent must never open a PR autonomously, even when commits land cleanly and the branch "feels finished".
+- `git merge` is allowed for local merges. Use it to integrate feature branches when needed.
+- Never commit directly to `main` for feature work — always go through a feature branch first.
+- Always work on a feature branch — create one only if not already on a non-`main` branch.
+- **Append commits to the existing feature branch** when continuing related work. Don't spin up a new branch per request.
+- One logical *initiative* per branch (not one commit per branch). Multiple commits per branch is normal and preferred.
+- Keep branches short-lived — they exist until the user decides to merge or open a PR.
+- The `superpowers:finishing-a-development-branch` skill does NOT apply in this project — agent workflow ends at commit. Push, PR, and remote integration require explicit user action.
+
+## Commit Rules
+
+### Format: Conventional Commits
+
+```
+<type>(<scope>): <description>
+```
+
+**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+**Scope:** module or area affected (e.g., `cli`, `repositories`, `logs`, `config`)
+
+### Examples
+
+```
+feat(cli): register logs command with filtering flags
+fix(repositories): pass GET query params via rest-client params key
+test(logs): add handler unit tests with mock repositories
+refactor(presenters): extract shared column definitions
+docs(logs): add RDoc documentation for public API
+```
+
+### Commit Discipline
+
+- Commit after each logical unit of work (TDD cycle: test → implement → refactor)
+- Never bundle unrelated changes in one commit
+- Write imperative mood descriptions: "add", "fix", "remove" — not "added", "fixes"
+- **NEVER add `Co-Authored-By` trailers** — this is a hard rule, no exceptions. Do not add any Co-Authored-By, Signed-off-by, or similar trailers to commit messages. This applies to ALL commits: manual, from subagents, from scripts. When dispatching subagents that commit, explicitly instruct them: "Do NOT add Co-Authored-By or any trailers to commit messages."
+- When the user asks to commit — execute immediately, no questions asked
+
+### TDD Commit Rhythm
+
+Following the red-green-refactor cycle, the natural commit points are:
+
+1. `test(scope): add failing test for <behavior>` — after writing the test (red)
+2. `feat(scope): implement <behavior>` — after making it pass (green)
+3. `refactor(scope): <what changed>` — after cleanup (refactor)
+
+Not every cycle needs 3 commits — use judgment. Small features can be one commit.

data/.claude/rules/proxmox-api-docs.md

@@ -0,0 +1,58 @@
+# Proxmox API Documentation Rules
+
+## MUST consult official sources before implementing API calls
+
+When implementing or modifying any Proxmox API interaction (repositories, endpoints, parameters), you MUST:
+
+1. **Check the local Proxmox API reference** in `docs/proxmox-api/` (JSON files parsed from official `apidata.js`):
+   - Files are organized by API section: `nodes-qemu-status.json`, `nodes-lxc-config.json`, `storage.json`, etc.
+   - Each file contains a flat array of endpoint objects with: `path`, `info` (per HTTP method with `parameters`, `returns`, `description`), `permissions`
+   - Use `Read` tool to inspect the relevant file for your endpoint
+   - Use `Grep` to search across all files: `grep -r "endpoint-keyword" docs/proxmox-api/`
+
+2. **Check the proxmox-api gem documentation** via `context7` MCP server with library ID `/L-Eugene/proxmox-api` to verify:
+   - Correct Ruby client usage and method chaining
+   - How to pass parameters (remember the `params:` key fix — see MEMORY.md)
+
+## File naming convention
+
+| File | Covers |
+|------|--------|
+| `nodes-qemu-status.json` | `/nodes/{node}/qemu/{vmid}/status/*` (start, stop, current, etc.) |
+| `nodes-qemu-config.json` | `/nodes/{node}/qemu/{vmid}/config` (VM configuration — large file, use offset/limit) |
+| `nodes-qemu-snapshot.json` | `/nodes/{node}/qemu/{vmid}/snapshot/*` |
+| `nodes-qemu-firewall.json` | `/nodes/{node}/qemu/{vmid}/firewall/*` |
+| `nodes-qemu-agent.json` | `/nodes/{node}/qemu/{vmid}/agent/*` |
+| `nodes-qemu-migrate.json` | `/nodes/{node}/qemu/{vmid}/migrate` |
+| `nodes-lxc-status.json` | `/nodes/{node}/lxc/{vmid}/status/*` |
+| `nodes-lxc-config.json` | `/nodes/{node}/lxc/{vmid}/config` |
+| `nodes-lxc-snapshot.json` | `/nodes/{node}/lxc/{vmid}/snapshot/*` |
+| `nodes-storage.json` | `/nodes/{node}/storage/*` (node-level storage) |
+| `nodes-tasks.json` | `/nodes/{node}/tasks/*` |
+| `nodes-disks.json` | `/nodes/{node}/disks/*` |
+| `storage.json` | `/storage/*` (cluster-level storage config) |
+| `access.json` | `/access/*` (auth, users, roles, tokens) |
+| `cluster-*.json` | `/cluster/*` (HA, backup, firewall, SDN, etc.) |
+
+## Updating the API reference
+
+If `docs/proxmox-api/` is empty or outdated, regenerate with the update script:
+
+```bash
+bash docs/proxmox-api-update.sh
+```
+
+## MUST NOT
+
+- **Guess or invent endpoint paths** — always verify against the local API reference
+- **Assume parameter names** — Proxmox naming is inconsistent (e.g., `vmid` vs `id`, `reboot` vs `restart`)
+- **Assume HTTP methods** — some operations use unexpected methods
+- **Copy patterns from other APIs** — Proxmox has its own conventions
+
+## Known Proxmox API gotchas
+
+- LXC restart uses endpoint `reboot`, not `restart`
+- LXC does NOT support `reset`, `suspend`, `resume`
+- Task status endpoint returns UPID format strings
+- Some endpoints use `POST` for read-like operations (e.g., task log with pagination)
+- Storage content listing requires `content` parameter to filter by type

data/.claude/rules/rbs-signatures.md

@@ -0,0 +1,80 @@
+# RBS Type Signatures Rules
+
+## MUST maintain RBS signatures alongside code changes
+
+Every time you create, modify, or delete a Ruby file under `lib/`, you MUST update the corresponding RBS signature file under `sig/`.
+
+### When creating a new file
+
+- Create `sig/pvectl/<path>.rbs` mirroring `lib/pvectl/<path>.rb`
+- Include signatures for all public and private methods, attr_readers, constants, and class inheritance
+- Follow existing RBS conventions in the project (see below)
+
+### When modifying an existing file
+
+- Update the corresponding `.rbs` file to reflect:
+  - New methods added
+  - Changed method signatures (parameters, return types)
+  - Removed methods
+  - Changed visibility (public/private)
+  - New or changed constants
+  - Changed inheritance or module includes
+
+### When deleting a file
+
+- Delete the corresponding `.rbs` file
+
+### When renaming/moving a file
+
+- Rename/move the corresponding `.rbs` file to match the new path
+
+## Validation
+
+After creating or modifying `.rbs` files, validate syntax:
+
+```bash
+BUNDLE_GEMFILE="" rbs parse sig/pvectl/<path>.rbs
+```
+
+The `rbs` gem is NOT in the project's Gemfile — always use `BUNDLE_GEMFILE=""` to bypass bundler.
+
+## Conventions
+
+Follow these established project conventions:
+
+| Convention | Example |
+|------------|---------|
+| Nullable types | `String?` for values that can be nil |
+| Boolean predicates | `def running?: () -> bool` |
+| API data hashes | `Hash[Symbol, untyped]` |
+| Void returns | `-> void` for methods with no meaningful return |
+| VMIDs/CTIDs | `Integer` (or `Integer \| String` when API accepts both) |
+| UPIDs | `String` |
+| Gem boundary types | `untyped` for objects from external gems (GLI, ProxmoxAPI, TTY, Pastel) |
+| Optional parameters | `?String name` for positional, `?key: String` for keyword |
+| Block parameters | `{ (String) -> void }` or `{ () -> String }` |
+
+### RBS limitations to remember
+
+- **No `protected`** — use `private` instead (RBS only supports `public` and `private`)
+- **No `extend untyped`** — list class methods directly with a comment
+- **No `nil` in tuple literals** — use `[String?, String?]` instead of `[String, String] | [nil, nil]`
+
+## Order of operations
+
+RBS updates fit into the documentation workflow (see `documentation-updates.md`):
+
+```
+1. Implement changes
+2. Update RBS signatures          ← here
+3. Verify (tests pass, rbs parse clean)
+4. Update CHANGELOG.md
+5. Update README.md (if user-facing)
+6. Propose CLAUDE.md update (if architecture changed)
+7. Commit
+```
+
+## When to skip
+
+- Changes to files outside `lib/` (tests, config, docs, `.claude/` rules)
+- Changes to `lib/pvectl/version.rb` — `VERSION` constant is already in `sig/pvectl.rbs`

data/.claude/rules/refactoring-as-design-option.md

@@ -0,0 +1,35 @@
+# Refactoring Rules
+
+## Reactive refactoring — propose, don't act
+
+When you spot existing code that needs improvement while working on a task — propose the refactoring to the user but wait for approval before making changes. Do NOT silently refactor surrounding code.
+
+## Refactoring as a design option — don't dismiss it
+
+When designing an approach for new functionality, if refactoring existing code would provide a better foundation — do NOT automatically dismiss it in favor of the path of least resistance.
+
+Instead, present it as one of the considered approaches with clear trade-offs:
+
+| Factor | Describe |
+|--------|----------|
+| **Cost** | What needs to change, how many files, risk of regressions |
+| **Benefit** | Simpler integration, reduced duplication, better extensibility |
+| **Alternative** | What the non-refactoring approach looks like and its downsides |
+
+Use `AskUserQuestion` to discuss the trade-offs and let the user decide.
+
+### When this applies
+
+- When proposing approaches for a new feature — refactoring should be one of the 2-3 considered approaches when relevant
+- During implementation — if you discover that refactoring would significantly simplify the current or upcoming work
+- When adding a new resource/handler/command that is structurally similar to existing ones with code duplication
+
+### When this does NOT apply
+
+- Cosmetic improvements (renaming, reformatting) unrelated to the current task
+- Refactoring that only benefits hypothetical future features (violates YAGNI)
+- Changes where the refactoring cost clearly outweighs the benefit — use judgment
+
+### Relationship to YAGNI/KISS
+
+Refactoring to simplify integration of a **current** feature is NOT over-engineering — it's applying KISS. The test: "Does this refactoring make the feature I'm building right now simpler?" If yes, it's a valid option worth discussing.

data/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"7f14d39a-39de-4e2c-b08f-00aa88f114c4","pid":25781,"procStart":"Sun May 17 18:41:59 2026","acquiredAt":1779126762839}

data/.claude/settings.json

@@ -0,0 +1,51 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit(./**)",
+      "Write(./**)",
+      "Bash(touch ./*:*)",
+      "Bash(find .:*)",
+      "Bash(find ./:*)",
+      "Bash(git init:*)",
+      "Bash(git add:*)",
+      "Bash(git rm:*)",
+      "Bash(git reset:*)",
+      "Bash(git commit:*)",
+      "Bash(git checkout:*)",
+      "Bash(git branch:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git pull:*)",
+      "Bash(git merge:*)",
+      "Bash(git restore:*)",
+      "Bash(git stash:*)",
+      "Bash(git ls-remote:*)",
+      "Bash(bundle info:*)",
+      "Bash(gem contents:*)",
+      "Bash(GLI_DEBUG=true bundle exec exe/pvectl:*)",
+      "WebSearch",
+      "AskUserQuestion",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:rubygems.org)",
+      "WebFetch(domain:rubystyle.guide)",
+      "WebFetch(domain:www.rubydoc.info)",
+      "WebFetch(domain:docs.ruby-lang.org)",
+      "WebFetch(domain:ruby-doc.org)",
+      "WebFetch(domain:rubyapi.org)",
+      "WebFetch(domain:davetron5000.github.io)",
+      "WebFetch(domain:pve.proxmox.com)",
+      "WebFetch(domain:docs.claude.com)",
+      "mcp__context7__*",
+      "mcp__acp__Bash"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "context7"
+  ],
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

data/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}

data/.ruby-gemset

@@ -0,0 +1 @@
+pvectl

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.3.0

data/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **describe**: Firewall Rules section in `describe vm`, `describe container`, and `describe node` output — top-level table with ENABLED, TYPE, ACTION, PROTO, SOURCE, DEST, COMMENT columns
+- **describe vm**: Block Device Statistics section with per-disk read/write bytes and IOPS
+- **describe vm**: Balloon memory details (actual, max, free, total inside guest) in Memory section
+- **commands**: Node DNS configuration — `pvectl get dns --node NODE` reads per-node DNS resolver settings; `pvectl edit dns NODE` opens DNS configuration (search domain, dns1, dns2, dns3) in an interactive YAML editor with diff preview and `--dry-run` support
+- **commands**: Node systemd services — `get services`, `pvectl service start/stop/restart/reload`
+- **commands**: `pvectl get time` — show node time and timezone (single node via `--node`, otherwise iterates online nodes)
+- **commands**: `pvectl set node N timezone=...` — change node timezone via the dedicated `/nodes/{node}/time` API endpoint
+- **commands**: Node hosts file editing — `edit hosts NODE` opens `/etc/hosts` in editor and posts back with original digest for optimistic locking, plus `get hosts --node NODE` to read raw contents
+- **commands**: APT package management — `pvectl apt list/update/changelog/versions`
+- **commands**: `pvectl wakeonlan node <NAME>` — send Wake-on-LAN to a cluster node via `POST /nodes/{node}/wakeonlan`; surfaces the MAC address used for the magic packet on success
+- **commands**: `pvectl get node-capabilities` (aliases: `capabilities`, `caps`) — list supported QEMU CPU models and machine types per node via `/nodes/{node}/capabilities/qemu/*`
+- **commands**: `pvectl move disk vm/ct` — migrate disk/volume between storages on same node (`--target STORAGE`, `--format` for VMs, `--delete-source`, `--bandwidth`, `--wait`, `--timeout`, `-y`)
+- **repositories**: `Vm#move_disk` and `Container#move_volume` wrapping Proxmox `move_disk`/`move_volume` endpoints
+- **services**: `Services::MoveDisk` orchestrates async repository call + optional task polling and returns a typed `OperationResult`
+- **commands**: Cloud-init management — `pvectl cloudinit regenerate/pending/dump vm` to rebuild the cloud-init ISO, list pending configuration changes, and print generated user/network/meta YAML
+- **commands**: `pvectl sendkey vm` — send QEMU keycodes to a running VM (e.g., ctrl-alt-delete)
+- **commands**: `pvectl get subscription` — show Proxmox subscription status per node (level, status, next due date, masked key). Use `-o wide` to reveal the full license key.
+- **commands**: `pvectl feature vm/ct` — query availability of clone/snapshot/copy for a VM or container
+- **commands**: `pvectl unlink disk vm` — remove disk from VM config without deleting volume (or `--force` to delete)
+
+### Changed
+- **describe**: rules are no longer nested under the `Firewall` section as a `Rules` sub-table; they are rendered in the dedicated `Firewall Rules` top-level section
+
+### Fixed
+
+### Removed
+
+### Documentation
+
+## [0.2.0] — 2026-05-17
+
+### Added
+- **commands**: `pvectl pull` command — export VM/container configuration as kubectl-like YAML manifests (single, multiple, `--all`, selectors) with diff preview, `--yes`, `--dry-run` for file output
+- **commands**: `pvectl push` command — apply YAML manifests to cluster (create or update resources) with diff preview, `-f`/`--file`, stdin pipe support, auto-VMID allocation, `--yes`, `--dry-run`, post-apply manifest refresh
+- **manifest-serializer**: kubectl-like manifest format with `apiVersion`/`kind`/`metadata`/`spec` envelope
+- **config-serializer**: `to_nested`/`from_nested` methods for structured config with parsed complex values
+- **config-serializer**: bidirectional value parsing for complex Proxmox config strings (network, disk, boot, agent, startup, ipconfig)
+- **commands**: `pvectl set` command for non-interactive resource configuration (vm, container, volume, node) with key=value syntax
+- **commands**: `pvectl edit volume` for interactive volume property editing via YAML editor
+- **commands**: `pvectl edit node` for interactive node configuration editing via YAML editor
+- **commands**: `pvectl get volume <vm|ct> <ID...>` and `pvectl get volume --storage <STORAGE>` list virtual disk volumes from VM/CT config or storage content API
+- **commands**: `pvectl describe volume <vm|ct> <ID> <disk_name>` shows detailed information about a specific virtual disk
+- **volumes**: Volume selector with `-l format=raw,storage=local-lvm` filtering for `get volume`
+- **describe disk**: `pvectl describe disk /dev/xxx [--node NODE]` shows device info and structured SMART attributes (ATA table or parsed NVMe/SAS key-value pairs)
+- **parsers**: SmartText parser for converting NVMe/SAS smartctl text output into structured data
+- **repositories**: `Disk#smart` method for SMART data retrieval from Proxmox API (`GET /nodes/{node}/disks/smart`)
+- **cli**: `get disks` command to list physical disks (block devices) on cluster nodes with `--node` filtering
+- **cli**: `get disk` alias for `get disks`
+- **cli**: selector support for disks (`-l type=ssd,health=PASSED,node=pve1,gpt=yes,mounted=yes`)
+- **selectors**: support `template` field filtering for VMs and containers (`-l template=yes`, `-l template=no`)
+- **cli**: `-l`/`--selector` flag for `get` command enables kubectl-style filtering for VMs and containers (e.g., `-l status=running,tags=prod`, `-l name=~web-*`)
+- **cli**: `--status` flag acts as shortcut for `-l status=VALUE` for VM/CT resources, combinable with other selectors
+- **cli**: `pvectl template vm/ct` command for converting VMs and containers to Proxmox templates (irreversible, with confirmation prompt or `--yes` flag, `--force` to stop running resources)
+- **cli**: `pvectl get templates` handler for listing templates with optional `--type vm|ct` filter
+- **models**: `type` attribute added to VM and Container models (distinguishes `qemu`/`lxc`)
+- **cli**: `pvectl get tasks` command for cluster-wide task listing with `--node`, `--limit`, `--since`, `--until`, `--type`, `--status` filtering flags
+- **rbs**: Full RBS type signatures for the entire codebase (175 files, ~4300 lines under `sig/`)
+- **rbs**: External stubs for GLI and ProxmoxAPI gems (`sig/external/`)
+- **rbs**: Pragmatic typing strategy — strict types for domain layer, `untyped` at gem boundaries
+- **console**: Interactive terminal session for VMs and containers via `pvectl console vm|ct <ID>`
+- **console**: WebSocket-based xtermjs protocol with native Ruby implementation (websocket-driver gem)
+- **console**: Session authentication with interactive credential prompt when API token is insufficient
+- **plugins**: Plugin system with gem-based (`pvectl-plugin-*`) and directory-based (`~/.pvectl/plugins/*.rb`) discovery
+- **plugins**: `PluginLoader` class for automatic plugin loading with graceful error handling
+- **commands**: `SharedFlags` module for reusable flag definitions across commands
+- **commands**: `SharedConfigParsers` mixin module for shared CLI flag parsing (disks, nets, cloud-init, mountpoints) across create and clone commands
+- **cli**: Configuration flags for `pvectl clone vm/ct` — modify CPU, memory, disks, network, and other settings during clone (two-step: clone then config update via PUT API)
+- **models**: `:partial` status on `OperationResult` for operations that partially succeed (e.g. clone OK but config update failed)
+- **resize**: `pvectl resize disk vm/ct <id> <disk> <size>` command for resizing VM and container disks with confirmation prompt and `--yes` flag
+- **describe**: `pvectl describe snapshot <name> [vmid...]` command showing detailed snapshot metadata with visual snapshot tree
+
+### Changed
+- **config-serializer**: section layout restructured to match Proxmox UI tabs (hardware/options/cloud-init for VM, resources/network/dns for CT)
+- **edit**: output format updated to reflect new section layout (hardware wrapper, options section)
+- **describe vm**: reorganize output to match PVE web UI tabs (Summary, Hardware, Cloud-Init, Options, Task History, Snapshots, Pending Changes) with previously hidden config keys (ACPI, KVM, Tablet, Freeze CPU, Local Time, NUMA) now visible in Options section
+- **describe container**: reorganize output to match PVE web UI tabs (Summary, Resources, Network, DNS, Options, Task History, Snapshots, High Availability) with all options visible
+- **describe**: add Task History section showing recent operations for VM and container resources
+- **get**: `storages` is now the primary resource name (consistent with `vms`, `nodes`, etc.); `storage` and `stor` remain as aliases
+- **commands**: `pvectl edit` now supports `volume` and `node` resource types in addition to `vm` and `container`
+- **presenters**: reduce default table columns to 6 (NAME, ID, STATUS, NODE, CPU, MEMORY); UPTIME, TEMPLATE, TAGS moved to wide output
+- **presenters**: NAME column now appears first (before VMID/CTID), matching kubectl convention
+- **presenters**: extract shared display helpers (format_bytes, uptime_human, tags_display, template_display) to Presenters::Base
+- **cli**: boolean config flags (`--start`, `--numa`, `--agent`, `--privileged`, `--onboot`) now support negation (`--no-start`, `--no-agent`, etc.) in `create` and `clone` commands
+- **cli**: Unified snapshot CLI syntax — snapshot name is now a positional argument, VMIDs use `--vmid` flag (repeatable), `--node` filters by node, `--all` deletes all snapshots (**breaking change**)
+- **cli**: `create snapshot` and `delete snapshot` are now GLI sub-commands with dedicated flags
+- **cli**: `get snapshots` and `describe snapshot` accept `--vmid` and `--node` flags
+- **services**: Snapshot service methods accept `node:` parameter for node filtering
+- **services**: Added `delete_all` method for removing all snapshots from VMs
+- **cli**: `pvectl get snapshots`, `pvectl create snapshot`, and `pvectl delete snapshot` without VMIDs now operate cluster-wide (previously required at least one VMID)
+- **commands**: Extracted `IrreversibleCommand` mixin from `DeleteCommand` for reuse in template and other destructive commands
+- **services**: Extract `Services::TaskListing` from `Logs::Handlers::TaskLogs` for shared multi-node task listing logic
+- **cli**: Refactored all command definitions from inline `cli.rb` to self-registration via `.register(cli)` class methods
+- **cli**: `cli.rb` reduced from ~930 lines to ~96 lines (globals, error handling, PluginLoader)
+- **cli**: `template` command now uses `--yes` to skip confirmation (was `--force`) for consistency with `delete` and other destructive commands
+- **cli**: `template --force` now stops running VMs/containers before conversion (matching `delete --force` behavior)
+- **cli**: `ArgvPreprocessor` refactored to use dynamic GLI reflection instead of static flag maps — automatically discovers all registered flags and switches
+- **commands**: `CreateVm` and `CreateContainer` refactored to use `SharedFlags` config groups and `SharedConfigParsers` mixin, eliminating inline flag definitions and parser method duplication
+
+### Fixed
+- **push**: transform disk values to Proxmox create API format (`STORAGE_ID:SIZE_IN_GiB`) — strip volume names, handle cloud-init, EFI/TPM, and empty CD-ROM
+- **push**: normalize cloud-init volume names symmetrically in both directions (API→manifest and manifest→flat), preventing false diffs and invalid create params
+- **push**: complete manifest values from API before update diff — fill missing sub-properties (volume names, MAC addresses, cloudinit size) and restrict diff to manifest-only keys, preventing false diffs for default/omitted values
+- **push**: coerce numeric strings from YAML manifests to integers for consistent comparison with API values (e.g., `memory: '2048'` vs `2048`)
+- **push**: filter nil/empty values from create params and extract detailed error info from Proxmox API responses
+- **push**: detect disk size changes and use Proxmox resize API instead of config PUT (which only updates metadata without actually resizing the disk)
+- **push**: refresh unchanged manifest files with server-assigned values (MAC addresses, volume names, UUIDs) even when no config changes need to be applied
+- **push**: track async task completion for resize and create operations — report actual success/failure instead of fire-and-forget
+- **repositories**: use server-side `/cluster/nextid` API for VMID/CTID allocation instead of client-side scanning (fixes stale config file conflicts)
+- **pull**: rename `-o` flag to `-f`/`--file` to avoid conflict with global `-o`/`--output` format flag
+- **presenters**: rename misleading "Wearout" label to "Life Remaining" in describe disk output (Proxmox reports remaining life, not wear percentage)
+- **presenters**: remove "Mounted" field from describe disk output (mount status applies to partitions, not whole disks)
+- **services**: `--agent` and `--onboot` now correctly send disable value to API when negated (previously only supported enabling)
+- **services**: `create container` no longer forces `unprivileged: 1` when `--privileged` flag is not specified (respects API defaults)
+- **cli**: `--status` flag now correctly filters VMs and containers by status in `get` command (previously ignored for VM/CT resources)
+- **wizards**: Remove duplicate confirmation prompt in `create vm` and `create ct` interactive wizards — wizard no longer asks "Create this VM/container?" before showing the summary; only the summary-based confirmation remains
+- **presenters**: Clone operation output now displays the new (cloned) resource data (VMID/CTID, name, node) instead of the source resource data
+- **config**: `SimplePrompt` fallback now supports `required:`, `convert:`, and extra keyword arguments matching `TTY::Prompt#ask` interface (fixes `unknown keyword: :required` in interactive `create` wizard)
+- **cli**: Command flags placed after positional arguments are now correctly reordered (e.g., `pvectl delete vm 103 --yes` now works as expected)
+
+### Removed
+- **commands**: `pvectl resize volume` command (replaced by `pvectl set volume ... size=+10G`)
+
+### Documentation
+- **cli**: Added `long_desc` man-page style help text to all commands (~25 commands) with DESCRIPTION, EXAMPLES, NOTES, and SEE ALSO sections
+- **cli**: Enabled `wrap_help_text :verbatim` for proper formatting of code examples in help output
+- **cli**: Enabled `sort_help :manually` to display commands in logical declaration order
+- **readme**: Transformed README from 529-line reference into ~130-line landing page with links to GitHub Wiki
+- **wiki**: Created comprehensive GitHub Wiki with 10 pages: Home, Getting Started, Command Reference, Configuration Guide, Selectors & Filtering, Output Formats, Workflows, Plugin Development, Troubleshooting, FAQ