Make "chub get" version-aware for the agent environment

[snovaisg]

Problem

chub get can return docs that are valid for a different runtime/library version than the agent’s actual environment. This creates avoidable implementation errors (wrong method names, params, behavior) and rework.

Current limitation: there is no explicit env-version matching mode, no mismatch policy control, and no machine-readable diagnostics to help agents decide whether a result is safe to use.

Proposed Solution

Implement a minimal, opt-in env-version matching feature for chub get:

• Add flags:
  • --match-env <python|node|auto>
  • --mismatch <strict|warn>
• Add shared matcher logic that evaluates:
  • available doc versions
  • detected/hinted version
  • policy (strict|warn)
• Support minimal env hints provided by the agent:
  • detectedVersion
  • confidence (installed|locked|declared|unknown)
• Add JSON diagnostics when --json is used with env matching:
  • match.status (exact|compatible|mismatch|undetermined)
  • match.selectedVersion
  • match.requestedVersion
  • policy
  • warnings
• Behavior requirements:
  • No --match-env => existing behavior unchanged
  • strict => fail closed on mismatch/undetermined
  • warn => return fallback with explicit warning

Alternatives Considered

1. Leave version compatibility entirely to the agent (status quo).

• Rejected because the tool currently does not provide explicit instructions or guardrails for the agent to find docs compatible with its environment version. That makes usage risky: agents may confidently select incompatible docs without a clear mismatch signal or policy-driven failure path.

2. Always-on matching by default.

• Rejected for now: backward compatibility risk and workflow disruption.

3. MCP + CLI parity in same PR.

• Rejected for now: increases scope; better as follow-up once CLI behavior is stable.

Additional Context

• This issue should follow a minimal-scope implementation focused on CLI get only, with targeted tests for:
  • backward compatibility (no env flags)
  • strict mismatch failure
  • warn mismatch fallback
  • undetermined behavior in strict vs warn
  • JSON output contract
• Include doc and skill guidance updates to avoid overclaiming exact version matches when evidence is weak.

[mvanhorn]

Submitted #182 to auto-select the language when a doc has only one variant. This addresses the simplest subset of version-aware get - when the choice is unambiguous, skip the prompt.