---
name: hwpod-ctl
description: Manage and validate HWLAB HWPOD runtime bindings from a code agent runner. The hwpod-ctl skill is separate from hwpod-cli and is used for hwpod-id validation, smoke checks, and explicit local spec import/export maintenance.
---

# hwpod-ctl

This skill follows Skill(cli-spec). It is the standard management entry for runtime-resolved HWPOD identity and node binding checks.

## Scope

`hwpod-ctl` is a peer of `hwpod-cli`, not a fallback task path. Use it to validate a service-resolved `hwpod-id`, inspect the four HWPOD elements, check node binding, and run smoke or temporary maintenance actions.

`hwpod-ctl` does not replace `hwpod-cli` for task execution. When a task needs source lookup, use `hwpod workspace rg/search` for symbol hunting and `hwpod workspace cat` only for full file bodies; when a task needs build/download/UART/job status, hand it back to `hwpod-cli` and its compiler-backed plan path.

## Commands

- Validate runtime HWPOD before hardware work: `hwpod-ctl spec validate --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`.
- Show the resolved HWPOD document: `hwpod-ctl spec show --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`.
- For explicit debug/import only, local YAML can still be passed with `--spec <path>`; do not use this as a runner default.

## Boundaries

- `hwpod-ctl` must not initialize or restore runner-local `.hwlab/hwpod-spec.yaml` to make a task pass. HWPOD authority is the runtime service and `hwpod-id`.
- `hwpod-node` must not receive or store the full `hwpod-spec`.
- Temporary maintenance commands belong here, not in normal `hwpod-cli` task flows.
