doca-comm-channel-admin

# DOCA Comm Channel Admin Tool

> **Actual binary contract.** `doca_comm_channel_admin` is one
> zero-application-argument, read-only scan-and-print operation.
> It scans every comch-capable `doca_dev` on the current side via
> `resourcedump` (MFT) and prints SERVERS and CONNECTIONS tables.
> It has no list, inspect, device-scope, drain, restart, or other
> application operation. This skill does not retain conceptual
> workflows under invented command names.

**Where to start:** This is a tool skill for invoking the DOCA Comm
Channel Admin Tool — the **read-only inventory** CLI counterpart
to the [`doca-comch`](../../libs/doca-comch/SKILL.md) library. The
shipped `doca_comm_channel_admin` binary takes **no arguments
beyond ARGP defaults** (`--help`, `--version`, `--log-level`,
`--sdk-log-level`, `--json`) and performs **one inventory pass**
per invocation: it walks every `doca_dev` on this side, filters
to comch-capable devices, shells out to `resourcedump` (MFT) on
each, and prints two ASCII tables (SERVERS and CONNECTIONS).
There is no `list` subcommand, no `inspect` subcommand, no
`drain` flag, and no `restart` flag — those are not part of the
tool's surface. Open [`TASKS.md`](TASKS.md) and start at
[`## run`](TASKS.md#run) for the single-shot invocation, or
[`## debug`](TASKS.md#debug) when the user reports the tool sees
a different channel set than the program. Open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what
the printed tables actually mean* and *what is not in this
tool's scope*. If the user has not installed DOCA yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the user
needs MFT (`resourcedump` on `PATH` with the privilege documented
for the installed release), `doca-setup` + `doca-public-knowledge-map`
cover that. If the user is holding pre-2.5 docs that mention
"Comm Channel", route to
[`doca-comch CAPABILITIES.md ## Version compatibility`](../../libs/doca-comch/CAPABILITIES.md#version-compatibility)
for the rename rule. If the user wants to *change* channel
state, route to the program-side
reconnect lifecycle in [`doca-comch`](../../libs/doca-comch/SKILL.md)
or to BlueField mode / driver reload in
[`doca-setup`](../../doca-setup/SKILL.md) +
[`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) — **not**
to this tool.

## Example questions this skill answers well

The CLASSES of admin-tool questions this skill is built to answer,
each with one worked example. The class is the load-bearing piece;
the worked example is one instance.

- **"Which comch servers and connections are currently visible?"** —
  worked example: *"print every server and connection row visible
  on this side"*. Answered by the scan-and-print surface in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the single invocation in
  [`TASKS.md ## run`](TASKS.md#run).
- **"What does the tool report for this server or connection?"** —
  locate the matching row in the SERVERS or CONNECTIONS table;
  there is no second per-channel query. Answered by
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + [`TASKS.md ## run`](TASKS.md#run).
- **"How do I know the admin tool's view matches what my Comch
  program sees?"** — worked example: *"the program reports
  CONNECTED but the admin tool lists zero channels"*. Answered by
  the cross-checking pattern in
  [`TASKS.md ## test`](TASKS.md#test) and the representor-binding
  layer in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
- **"Is this admin tool on my installed DOCA version, and does it
  match the comch library version?"** — worked example: *"is the
  tool available on DOCA 2.4"*. Answered by the overlay in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
  which redirects to the canonical
  [`doca-version`](../../doca-version/SKILL.md) rules and adds the
  Comm Channel Admin Tool specifics.
- **"The tool prints nothing — is the install broken or is there
  genuinely no channel?"** — worked example: *"`list` returned an
  empty result on a host with a known-good Comch client"*.
  Answered by the empty-output interpretation rules in
  [`TASKS.md ## debug`](TASKS.md#debug) +
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).

## Audience

This skill serves **external operators and AI agents who need to
inventory a host-DPU comch channel from the outside**
— after the [`doca-comch`](../../libs/doca-comch/SKILL.md) library
has been used to create the channel from a program. Concretely:

- A platform operator who runs a Comch-using service on BlueField
  and needs to confirm the channel is healthy before declaring the
  service ready.
- A developer of a Comch consumer who sees `DOCA_ERROR_AGAIN` or a
  silent stall on the program side and wants to read the channel's
  state from outside the program rather than guessing.
- An AI agent capturing the external server/connection rows before
  recommending a program-side code or lifecycle change.

It is **not** for users debugging the admin tool itself, **not** a
substitute for the live public DOCA Comm Channel Admin Tool guide,
and **not** the right place for users learning the comch API —
that audience belongs in
[`doca-comch`](../../libs/doca-comch/SKILL.md).

The tool is shipped as a CLI binary under
`/opt/mellanox/doca/tools/`, not a library you link against. The
skill uses the same `kind: tool` three-file shape as the rest of
the bundle so the agent's task-verb contract
(`configure / build / modify / run / test / debug`) is uniform
across libraries, services, and tools.

## When to load this skill

Load this skill when the user is — or the agent needs to — invoke
the DOCA Comm Channel Admin Tool on a real host or BlueField Arm
with DOCA installed (or inside the public NGC DOCA container with
the right device passthrough). Concretely:

- Listing currently active comch channels on a host or DPU.
- Reading the r