How Context Hub Handles Version-Specific Documentation: Complete Technical Guide

Context Hub treats every package SDK version as a first-class dimension by parsing version declarations from front-matter, merging them into a unified registry structure, and resolving specific or latest versions at runtime through the resolveDocPath function.

The andrewyng/context-hub repository implements a sophisticated version resolution system that allows documentation authors to maintain separate guides for different SDK releases while giving CLI users seamless access to the correct content. This architecture ensures that agents and developers always receive documentation matching their installed package version.

Declaring Versions in Front-Matter

Documentation authors specify supported package versions directly in the DOC.md front-matter using the metadata.versions field (or the shorthand versions key). This comma-separated list declares which SDK versions the document covers.

name: openai/chat
description: Python SDK for OpenAI Chat
metadata:
  languages: python
  versions: 2.0.0,1.0.0

During the chub build process, the build script expands this declaration into an array of structured objects containing the version string, file path, and associated files. Each version maps to a distinct directory structure, isolating version-specific content at the filesystem level.

How the Registry Indexes Multiple Versions

The registry system in cli/src/lib/registry.js (lines 73-78, 150-158) merges all DOC.md files sharing the same name into a single entry containing a languages[] array. Each language object maintains its own independent versions[] array.

{
  "id": "openai/chat",
  "languages": [
    {
      "language": "python",
      "versions": [
        { "version": "2.0.0", "path": "openai/chat/python/v2", "files": [] },
        { "version": "1.0.0", "path": "openai/chat/python/v1", "files": [] }
      ],
      "recommendedVersion": "2.0.0"
    }
  ]
}

The build process automatically calculates the highest semver across all versions and stores it as recommendedVersion, ensuring the CLI can default to the latest stable documentation when users omit specific version flags.

Resolving Versions at Runtime

The core version resolution logic resides in resolveDocPath() within cli/src/lib/registry.js (lines 504-518). This function accepts an entry, language, and optional version parameter, then returns the precise path to the correct documentation files.

export function resolveDocPath(entry, language, version) {
  const lang = language ? normalizeLanguage(language) : null;
  
  // Language lookup logic omitted for brevity...
  
  if (version) {
    // User supplied a version flag
    verObj = langObj.versions?.find(v => v.version === version);
    if (!verObj) {
      return {
        versionNotFound: true,
        requested: version,
        available: langObj.versions?.map(v => v.version) || [],
      };
    }
  } else {
    // No flag → use the recommended (latest) version
    const rec = langObj.recommendedVersion;
    verObj = langObj.versions?.find(v => v.version === rec) || langObj.versions?.[0];
  }
  // Return resolved path...
}

Automatic Latest Version Selection

When users run chub get openai/chat without specifying --version, the CLI automatically selects recommendedVersion (or falls back to the first version in the array if the field is missing). This guarantees that agents receive the most current documentation without manual version management.

Handling Missing Version Requests

If a user requests a version that does not exist (e.g., --version 9.9.9), resolveDocPath returns a versionNotFound payload containing the requested string and an array of available versions. The get command in cli/src/commands/get.js (lines 47-52) catches this result and surfaces a user-friendly error:

if (resolved.versionNotFound) {
  error(
    `Version "${resolved.requested}" not found for "${id}". ` +
    `Available versions: ${resolved.available.join(', ')}`,
    globalOpts
  );
}

Multi-Language Version Independence

Context Hub supports per-language version lists, enabling scenarios where Python SDK v2.0.0 coexists with JavaScript SDK v1.5.0 under the same documentation entry. The resolver first selects the language slice using the --lang flag, then searches for the version within that language's specific versions[] array (lines 492-505 in cli/src/lib/registry.js).

# Get Python v1.0.0 specifically

chub get openai/chat --lang python --version 1.0.0

# Get JavaScript latest (might be different version number)

chub get openai/chat --lang javascript

Skills vs. Docs: Version-Agnostic Content

According to docs/design.md (lines 49-55), Skills represent a distinct content type that lacks both languages and versions fields. When retrieving skills via chub get, the CLI silently ignores --lang and --version flags, treating the content as universally applicable regardless of SDK version or programming language.

Summary

• Front-matter driven: Authors declare supported versions using comma-separated metadata.versions in DOC.md files.
• Registry aggregation: The build process merges versioned docs into a unified entry with languages[].versions[] structures and calculates recommendedVersion from semver comparisons.
• Smart resolution: The resolveDocPath() function in cli/src/lib/registry.js handles both explicit version requests and automatic latest-version fallback.
• Graceful errors: When a requested version does not exist, the CLI returns a clear message listing all available versions instead of failing silently.
• Cross-language flexibility: Each programming language maintains independent version lists, supporting divergent release cycles across SDKs.

Frequently Asked Questions

How do I specify multiple versions for a single documentation entry?

Add a comma-separated list to the versions key in your DOC.md front-matter. During chub build, the system expands this into distinct version objects within the registry, each pointing to its own directory path.

What happens if I request a version that doesn't exist?

The CLI prints a specific error message listing the available versions. The resolveDocPath function returns a versionNotFound object containing the requested version and an array of valid alternatives, which the get command renders as: Version "9.9.9" not found for "openai/chat". Available versions: 2.0.0, 1.0.0.

Does Context Hub support different version numbers for different programming languages?

Yes. Each language slice within a registry entry maintains its own versions[] array. This allows Python documentation to track versions 2.0.0 and 1.0.0 while JavaScript documentation simultaneously tracks 2.0.0 and 1.5.0, with independent recommendedVersion values for each language.

Are skills version-specific like SDK documentation?

No. Skills are version-agnostic by design. They lack both languages and versions fields in the registry schema, and the CLI ignores --version and --lang flags when retrieving them, as documented in docs/design.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}