Doca Version

---
license: Apache-2.0
name: doca-version
description: >
  Use this skill when the user is doing DOCA version handling —
  detecting the installed release, validating the four-way match
  across pkg-config doca-common, applications/VERSION, doca_caps
  --version, and bfver/mlnx-release on BlueField, reasoning about
  NGC container tags, looking up whether a capability is on the
  installed release, or diagnosing build-vs-runtime drift. Trigger
  even when the user does not explicitly say "DOCA version" or
  "four-way match" — typical implicit phrasings include "program
  built but does nothing on the wire", "undefined reference to a
  symbol the docs claim exists", "DOCA_ERROR_NOT_SUPPORTED at
  runtime", "counter didn't increment", "what does `latest` mean
  for this tag", or "is my LTS still supported". Refuse and route
  elsewhere for installing or choosing DOCA packages (doca-setup),
  per-library API/capability questions (matching library skill),
  the cross-library DOCA_ERROR_* taxonomy (doca-programming-guide),
  or the general debug ladder (doca-debug) — those belong to other
  skills.
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca.
---

# DOCA version

**Where to start:** This skill is the bundle's single source of
truth for DOCA *version handling*. Open
[`TASKS.md`](TASKS.md) if the user wants to *do* something with the
version (detect / validate / diagnose mismatch); open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what does
version handling cover* (the four-way match, the detection chain,
NGC semantics, the per-library overlay pattern). Every other skill
in the bundle that touches version routes here — they MUST NOT
redefine the rules.

## Example questions this skill answers well

The CLASSES of version-handling questions this skill is built to
answer, each with one worked example. The agent should treat the
*class* as the load-bearing piece — the worked example is a single
instance.

- **"What DOCA version do I actually have installed?"** — worked
  example: *"the docs say 3.3 but I'm not sure what's on this
  host"*. Answered by the canonical detection chain in
  [`TASKS.md ## configure`](TASKS.md#configure) +
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  source-of-truth table.
- **"My program built but does nothing on the wire — is my install
  consistent?"** — worked example: *"`pkg-config --modversion`
  says 3.3.0; `doca_caps --version` says 3.2.0"*. Answered by the
  four-way match rule in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)
  + the partial-install diagnosis in
  [`TASKS.md ## debug`](TASKS.md#debug).
- **"Is this DOCA capability / API / sample on the version I
  have?"** — worked example: *"is the symmetric-RSS hash mode in
  Flow 2.6.0"*. Answered by the version-matrix lookup procedure in
  [`TASKS.md ## test`](TASKS.md#test) (which uses the
  `version-matrix.json` schema defined in
  [`doca-structured-tools-contract`](../doca-structured-tools-contract/SKILL.md#schemas)
  with fallback to per-library docs via
  [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)).
- **"Can I run my host package version X against BFB version Y?"** —
  worked example: *"host is 3.3.0 LTS, BlueField BFB is 3.1.0"*.
  Answered by the routing to the
  [DOCA Compatibility Policy](https://docs.nvidia.com/doca/sdk/doca-compatibility-policy/index.html)
  documented in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility).
- **"I'm inside the NGC DOCA container — what does the version
  match look like?"** — worked example: *"do I still need to check
  pkg-config / applications/VERSION / doca_caps separately?"*.
  Answered by the NGC container rule in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)
  + the container path in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do I write a per-library version-compatibility section
  for a new skill?"** — worked example: *"adding `doca-comch` to
  the bundle, what does its `## Version compatibility` look
  like?"*. Answered by the per-library overlay pattern in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the worked-example template in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"My `apt list` shows DOCA `3.3.0109`, but `/etc/apt/sources.list.d/doca.list`
  is pinned at `latest` / a different release — is the next
  `apt install doca-*` going to silently upgrade me?"** — worked
  example: *"I rolled back BFB to 3.1.0105 but my sources still
  point at the latest channel."* Answered by the apt-source
  consistency precheck in
  [`TASKS.md ## apt-source consistency`](TASKS.md#apt-source-consistency),
  which enumerates the three legitimate shapes of a configured
  DOCA apt source (network URL, local file-repo, RHEL/OEL
  equivalent) and the *do-not-install-until-the-source-matches*
  rule that protects pinned installs from accidental drift.

## When to load this skill

Load this skill whenever version handling is the load-bearing
concern. The decision must be made **before** the agent composes
its first sentence — the activation checklist below is the same
one referenced from
[`AGENTS.md ## Cross-cutting overlay activation triggers`](../../AGENTS.md#cross-cutting-overlay-activation-triggers),
mirrored here so the activation rule is at hand whenever this skill
is consulted.

## Agent activation checklist — load this skill at the START of the answer when any cell below is true

| Trigger class | Concrete prompt-side signals (any one fires the overlay) |
| --- | --- |
| Direct version question | *"what DOCA version do I have"*, *"is X consistent"*, *"is feature Y supported on version Z"*, *"can I mix host package version A with BFB version B"*, *"is my LTS still supported"*, *"what does the version string mean"* |
| Container tag question | any prompt that mentions a specific NGC container tag, or asks about `latest`, or asks how to pin a tag in a Dockerfile / pod spec / Compose file. The agent MUST also cite the *"never invent a tag string from memory, never quote `latest` without confirming it"* rule from [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy). |
| Build vs runtime drift | any debug session where the symptom is *"the program built fine but DOCA_ERROR_NOT_SUPPORTED at runtime"*, *"undefined reference to a symbol the docs say exists"*, *"my code does nothing on the wire"*, *"counter didn't increment"* — these are the canonical partial-install symptoms |
| Upgrade / downgrade plan | the user is planning to upgrade or downgrade DOCA on a host already running other DOCA workloads, or to refresh the BFB on a BlueField pair already attached to a host |
| Per-artifact cross-link | a per-artifact skill's `## Version compatibility` section cross-links here for the rule body, OR the agent is about to author a new per-artifact skill and needs the overlay template |

When any cell above fires, the agent MUST:

1. Cite the **four-source detection chain** from [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) explicitly in the answer — `pkg-config --modversion doca-common` → `cat /opt/mellanox/doca/applications/VERSION` → `doca_caps --version` → `bfver` plus `cat /etc/mlnx-release` (BlueField hosts). Do not paraphrase or summarize the chain; cite the commands by name. Do NOT substitute `mlxprivhost` or `bfb-info` for the BFB leg — those are common hallucinations and the bundle explicitly bans them in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
2. State the **four-way match rule** from [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility) verbatim if the prompt could possibly involve a mismatch (every deploy-shape question and every debug-shape question can; orientation-shape questions usually cannot).
3. Refuse to invent a version string. If the agent doesn't have the actual `pkg-config --modversion` output from the user's host, the answer must say so and route to the detection chain — not assert a version from training-data recall.

## Universal version-coherence trigger

Whenever ANOTHER overlay (e.g. [`doca-setup`](../doca-setup/SKILL.md), [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md), [`doca-container-deployment`](../doca-container-deployment/SKILL.md), [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md)) calls a `## test` / `## configure` / `## modify` step that requires *"the install is healthy"* or *"versions are consistent"*, that step MUST resolve to a citation of this skill's four-source detection chain and four-way match rule. The agent does NOT redefine the rule per-overlay — every step that needs a version verification must route here. This is the *only* place in the bundle that owns the rule body.

Do **not** load this skill for general DOCA orientation, for
install procedures (use [`doca-setup`](../doca-setup/SKILL.md)),
or for library-specific API questions (use the matching library
skill).

## What this skill provides

This is a **thin loader**. The body keeps only the orientation
needed to pick the right next file. The substantive
version-handling material lives in two companion files:

- `CAPABILITIES.md` — the version-handling surface: the canonical
  source-of-truth table for version detection, the four-way match
  rule, NGC container semantics, the per-library overlay pattern,
  the routing to the DOCA Compatibility Policy, the error
  taxonomy for version-related failures (pkg-config missing,
  partial install, BFB/host mismatch, NGC mixing), the
  observability surface (which command to read for which version
  source), and the safety policy ("never invent a version, never
  quote `latest`").
- `TASKS.md` — step-by-step workflows for the six in-scope
  version verbs: `configure` (detect on this host), `build`
  (build-time match), `modify` (update a version pin in a build
  manifest), `run` (runtime check), `test` (four-way validation +
  version-matrix lookup), `debug` (diagnose mismatch / partial
  install). Plus a `Deferred task verbs` block.

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is in
   scope.
2. **For the version-detection sources, four-way match rule, NGC
   semantics, per-library overlay pattern, error taxonomy,
   observability, and safety policy, see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug — see [TASKS.md](TASKS.md).**

## Related skills

- [`doca-structured-tools-contract`](../doca-structured-tools-contract/SKILL.md) —
  the JSON schemas for the helper tools the agent should prefer
  when present. This skill's `## test` workflow uses the
  `version-matrix.json` schema defined there; do not redefine the
  schema here.
- [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md) —
  the routing table to public DOCA docs, including the
  Compatibility Policy. This skill cites the Compatibility Policy
  URL once via that map; it does not duplicate the routing.
- [`doca-setup`](../doca-setup/SKILL.md) — env-side install /
  verify / NGC container path. This skill assumes its
  preconditions are satisfied (i.e., something is installed
  somewhere; the version question is *what was installed and is
  it consistent*).
- [`doca-programming-guide`](../doca-programming-guide/SKILL.md) —
  program-side guidance (quote the version observed, header-wins,
  capability-discovery rules). The program-side `## Version
  compatibility` section there is now a 3-5 line redirect to this
  skill plus the program-side overlay (quote vs assume; never use
  agent-memory version).
- [`doca-debug`](../doca-debug/SKILL.md) — the cross-cutting
  debug ladder. Layer 2 (*version mismatch*) of that ladder is
  owned by this skill's `## debug` workflow.