@@ -664,6 +664,54 @@ Catalog installs resolve individual file URLs from the active step catalogs and
 then go through the same validation and commit path as `--dev` and `--from`.
 Discovery-only catalogs cannot be installed from.
 
+##### Catalog release history
+
+`specify workflow step info <id> --versions` lists the current and historical
+releases in the winning catalog. `specify workflow step add <id> --version <v>`
+selects the exact catalog release; without `--version`, `add` installs the
+advertised current release. The requested version never falls back to a
+lower-priority catalog, and discovery-only sources remain non-installable.
+`--version` cannot be combined with direct `--dev` or `--from` installs.
+
+Existing single-version catalog entries continue to work. Keep the current
+release's `version`, `step_yml_url` (or `url`), `init_url`, and optional files
+at the top level. An optional `releases` mapping adds historical versions:
+
+```json
+{
+  "steps": {
+    "my-step": {
+      "version": "2.0",
+      "step_yml_url": "https://example.com/my-step/2.0/step.yml",
+      "releases": {
+        "1.0": {
+          "step_yml_url": "https://example.com/my-step/1.0/step.yml",
+          "init_url": "https://example.com/my-step/1.0/__init__.py",
+          "extra_files": {"helper.py": "https://example.com/my-step/1.0/helper.py"},
+          "sha256": {
+            "step.yml": "<64 hex digits>",
+            "__init__.py": "<64 hex digits>",
+            "helper.py": "<64 hex digits>"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Each historical release must supply its own step URL and SHA-256 digest for
+every downloaded file. `init_url` can be omitted when derived from a
+`step_yml_url` ending in `step.yml`. To select the current version explicitly,
+its top-level entry must likewise supply the per-file `sha256` mapping.
+Release-specific files and requirements are not inherited from the current
+release. Repeated or malformed versions are rejected; equivalent PEP 440
+spellings such as `v1.0` and `1.0` select the same advertised release. The
+downloaded `step.yml` must declare the selected step ID and version. An
+unqualified legacy catalog install does not require digests or a step version.
+Only one version of each step ID can be installed at a time; use `--force` to
+replace a previous installation after reviewing the selected package.
+
 #### Replacement and force
 
 ```bash
 
@@ -40,6 +40,19 @@ class StepValidationError(StepCatalogError):
     """Validation error for step catalog config or step data."""
 
 
+class _DuplicateCatalogField(StepCatalogError):
+    """An ambiguous JSON object in a step catalog."""
+
+
+def _unique_json_fields(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _DuplicateCatalogField(f"Duplicate field '{key}' in step catalog.")
+        result[key] = value
+    return result
+
+
 # ---------------------------------------------------------------------------
 # StepCatalogEntry
 # ---------------------------------------------------------------------------
@@ -470,9 +483,11 @@ def _fetch_single_catalog(
         if cache_safe and not force_refresh and self._is_url_cache_valid(entry.url):
             try:
                 with open(cache_file, encoding="utf-8") as f:
-                    cached = json.load(f)
+                    cached = json.load(f, object_pairs_hook=_unique_json_fields)
                 if isinstance(cached, dict):
                     return cached
+            except _DuplicateCatalogField:
+                raise
             except (UnicodeDecodeError, json.JSONDecodeError, OSError):
                 # Ignore invalid/unreadable cache and fall back to fetching from source.
                 pass
@@ -530,15 +545,20 @@ def _validate_redirect(_old_url: str, new_url: str) -> None:
                         max_bytes=_max_json_catalog_bytes(),
                         error_type=StepCatalogError,
                         label="step catalog",
-                    ).decode("utf-8")
+                    ).decode("utf-8"),
+                    object_pairs_hook=_unique_json_fields,
                 )
+        except _DuplicateCatalogField:
+            raise
         except Exception as exc:
             if cache_safe and cache_file.exists():
                 try:
                     with open(cache_file, encoding="utf-8") as f:
-                        cached = json.load(f)
+                        cached = json.load(f, object_pairs_hook=_unique_json_fields)
                     if isinstance(cached, dict):
                         return cached
+                except _DuplicateCatalogField:
+                    raise
                 except (json.JSONDecodeError, ValueError, OSError):
                     # Stale-cache read failed; let the original fetch error propagate.
                     pass
@@ -574,6 +594,8 @@ def _get_merged_steps(
         for entry in reversed(catalogs):
             try:
                 data = self._fetch_single_catalog(entry, force_refresh)
+            except _DuplicateCatalogField:
+                raise
             except StepCatalogError:
                 fetch_errors += 1
                 continue
@@ -586,6 +608,7 @@ def _get_merged_steps(
                     step_data["_install_allowed"] = entry.install_allowed
                     merged[step_id] = step_data
             elif isinstance(steps, list):
+                seen_in_source: set[str] = set()
                 for step_data in steps:
                     if not isinstance(step_data, dict):
                         continue
@@ -594,6 +617,11 @@ def _get_merged_steps(
                         continue
                     step_id = str(raw_step_id).strip()
                     if step_id:
+                        if step_id in seen_in_source:
+                            raise StepCatalogError(
+                                f"Duplicate step ID '{step_id}' in catalog '{entry.name}'."
+                            )
+                        seen_in_source.add(step_id)
                         step_data["id"] = step_id
                         step_data["_catalog_name"] = entry.name
                         step_data["_install_allowed"] = entry.install_allowed
@@ -609,10 +637,13 @@ def search(
         query: str | None = None,
     ) -> list[dict[str, Any]]:
         """Search step types across all configured catalogs."""
+        from ._versions import available_versions
+
         merged = self._get_merged_steps()
         results: list[dict[str, Any]] = []
 
         for step_id, step_data in merged.items():
+            available_versions(step_data, step_id)
             step_data.setdefault("id", step_id)
             if query:
                 q = query.lower()
@@ -628,13 +659,18 @@ def search(
             results.append(step_data)
         return results
 
-    def get_step_info(self, step_id: str) -> dict[str, Any] | None:
-        """Get details for a specific step from the catalog."""
+    def get_step_info(
+        self, step_id: str, version: str | None = None
+    ) -> dict[str, Any] | None:
+        """Get the current or an exact release from the winning catalog."""
+        from ._versions import select_release
+
         merged = self._get_merged_steps()
         step = merged.get(step_id)
         if step:
             step.setdefault("id", step_id)
-        return step
+            return select_release(step, step_id, version)
+        return None
 
     def get_catalog_configs(self) -> list[dict[str, Any]]:
         """Return current catalog configuration as a list of dicts."""
 
@@ -0,0 +1,178 @@
+"""Release selection for step catalog entries."""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+from ._domain import StepCatalogError
+
+_DIGEST = re.compile(r"[0-9a-fA-F]{64}\Z")
+_CURRENT_ONLY = frozenset(
+    {
+        "version",
+        "url",
+        "step_yml_url",
+        "init_url",
+        "extra_files",
+        "sha256",
+        "requires",
+        "provides",
+        "releases",
+    }
+)
+
+
+def validate_checksums(entry: dict[str, Any], step_id: str, *, required: bool) -> None:
+    """Check that a release pins exactly the files its installer downloads."""
+    hashes = entry.get("sha256")
+    if hashes is None and not required:
+        return
+    files = entry.get("extra_files", {})
+    if not isinstance(files, dict) or any(
+        not isinstance(path, str)
+        or not path.strip()
+        or "\\" in path
+        or any(part in ("", ".", "..") for part in path.split("/"))
+        or PurePosixPath(path).is_absolute()
+        or path.casefold() in ("step.yml", "__init__.py")
+        or not isinstance(url, str)
+        or not url.strip()
+        for path, url in files.items()
+    ):
+        raise StepCatalogError(f"Step '{step_id}' has invalid extra_files.")
+    expected = {"step.yml", "__init__.py", *files}
+    if (
+        not isinstance(hashes, dict)
+        or hashes.keys() != expected
+        or any(
+            not isinstance(value, str) or not _DIGEST.fullmatch(value)
+            for value in hashes.values()
+        )
+    ):
+        raise StepCatalogError(
+            f"Step '{step_id}' needs SHA-256 digests for exactly {sorted(expected)}."
+        )
+
+
+def _validated_releases(
+    entry: dict[str, Any], step_id: str
+) -> dict[str, dict[str, Any]]:
+    if "releases" not in entry:
+        return {}
+    releases = entry["releases"]
+    if not isinstance(releases, dict):
+        raise StepCatalogError(f"Step '{step_id}' has an invalid releases mapping.")
+    if entry.get("id", step_id) != step_id:
+        raise StepCatalogError(f"Step '{step_id}' has a mismatched catalog ID.")
+    current = entry.get("version")
+    if not isinstance(current, str) or not current.strip():
+        raise StepCatalogError(f"Step '{step_id}' has releases but no current version.")
+    try:
+        seen = {Version(current)}
+    except InvalidVersion:
+        raise StepCatalogError(
+            f"Step '{step_id}' has invalid current version '{current}'."
+        ) from None
+    for release_version, record in releases.items():
+        if not isinstance(release_version, str) or not release_version.strip():
+            raise StepCatalogError(
+                f"Step '{step_id}' has an invalid release version key."
+            )
+        try:
+            normalized = Version(release_version)
+        except InvalidVersion:
+            raise StepCatalogError(
+                f"Step '{step_id}' has invalid release version '{release_version}'."
+            ) from None
+        if normalized in seen:
+            raise StepCatalogError(
+                f"Step '{step_id}' repeats release version '{release_version}'."
+            )
+        seen.add(normalized)
+        if not isinstance(record, dict):
+            raise StepCatalogError(
+                f"Step '{step_id}' release '{release_version}' must be an object."
+            )
+        if any(
+            key in record
+            for key in (
+                "id",
+                "version",
+                "releases",
+                "_catalog_name",
+                "_install_allowed",
+            )
+        ):
+            raise StepCatalogError(
+                f"Step '{step_id}' release '{release_version}' "
+                "contains reserved fields."
+            )
+        url = record.get("step_yml_url", record.get("url"))
+        if (
+            not isinstance(url, str)
+            or not url.strip()
+            or (
+                "url" in record
+                and "step_yml_url" in record
+                and record["url"] != record["step_yml_url"]
+            )
+        ):
+            raise StepCatalogError(
+                f"Step '{step_id}' release '{release_version}' needs a step.yml URL."
+            )
+        init_url = record.get("init_url")
+        if (
+            init_url is not None
+            and (not isinstance(init_url, str) or not init_url.strip())
+        ) or (init_url is None and not url.endswith("step.yml")):
+            raise StepCatalogError(
+                f"Step '{step_id}' release '{release_version}' "
+                "needs an __init__.py URL."
+            )
+        for field in ("requires", "provides"):
+            if field in record and not isinstance(record[field], dict):
+                raise StepCatalogError(
+                    f"Step '{step_id}' release '{release_version}' has invalid {field}."
+                )
+        validate_checksums(record, step_id, required=True)
+    return releases
+
+
+def select_release(
+    entry: dict[str, Any], step_id: str, version: str | None
+) -> dict[str, Any] | None:
+    """Select a release from the winning entry; never consult another source."""
+    releases = _validated_releases(entry, step_id)
+    current = entry.get("version")
+    if version is None or version == current:
+        return entry
+    try:
+        requested = Version(version)
+    except InvalidVersion:
+        return None
+    if isinstance(current, str):
+        try:
+            if requested == Version(current):
+                return entry
+        except InvalidVersion:
+            pass  # Legacy versions still support exact spelling above.
+    for advertised, record in releases.items():
+        if requested == Version(advertised):
+            common = {
+                key: value for key, value in entry.items() if key not in _CURRENT_ONLY
+            }
+            return {**common, **record, "version": advertised}
+    return None
+
+
+def available_versions(entry: dict[str, Any], step_id: str) -> list[str]:
+    """List the advertised current version before historical versions."""
+    releases = _validated_releases(entry, step_id)
+    current = entry.get("version")
+    if not isinstance(current, str) or not current:
+        return []
+    return [current, *sorted(releases, key=Version, reverse=True)]