feat: versioned metadata-only environment discovery (RFC 011)

[thegovind]

Summary

Implements the first metadata-only repository discovery profile from RFC 011,
merged in #1093.

• A packaged, versioned Environment Card and catalog schema, with strict
  source/path/revision and interface-role invariants.
• A deterministic producer over direct-child environment definitions in a
  pinned Git tree. It reuses authored manifest, package and README metadata,
  records provenance, and never imports candidate code.
• openenv catalog build, openenv catalog inspect, and a read-only
  openenv discover --catalog lexical baseline.
• Explicit incomplete reports, unknown evidence, atomic snapshot writes,
  same-snapshot identifier lookup, and correction/supersession/withdrawal
  comparison.
• A minimal authored Echo declaration and a revision-named CI snapshot artifact.

No runtime endpoint, environment installation, image pull, candidate probing,
tool invocation, reset/step, or execution-policy boolean is added.

Profile decisions

This draft implements 0.1-draft: GitHub source definitions, explicit publisher
configuration, complete inline snapshots, and declared interfaces only. It does
not pretend to verify RFC 008 runtime evidence or duplicate the normalized
validation manifest. Unsupported profiles and validated claims fail explicitly.

The initial inventory is the configured Git tree's direct-child openenv.yaml
definitions, not every deployment or community environment. Upstream source
revision bbd27cc959df6f6e7c961d58a9b0104be7aec0c9 produces 39 records.
A failed eligible record still makes the inventory incomplete; logging it does
not make the build complete.

The CLI requires an explicit snapshot. Automatic remote retrieval and a central
registry are not introduced. GitHub Actions artifacts are reviewable outputs,
not an assertion that every finder already indexes them.

Validation

• Applicable repository CI suite on Python 3.11 and 3.12: 1,834 passed,
  84 optional-dependency skips and 37 excluded integration/network/Docker cases
  in each matrix job.
• 65 discovery tests include a real temporary Git repository, byte-identical
  rebuilds, uncommitted-file isolation, symlink rejection, duplicate metadata,
  cross-revision mismatches, missing wire claims, malformed snapshots, exact
  lookup, lexical selection, and lifecycle failures. Wrong-root regressions
  recompute valid digests before asserting scope rejection.
• Combined local discovery and existing CLI coverage: 195 passed.
• Review regressions cover file-based versus text license declarations at both
  package and repository scope, conflicting file/text tables, and matching query
  cardinality across declaration/entry models and their packaged JSON schemas.
• The real 39-entry producer snapshot was consumed by an independently
  implemented HF discovery consumer. Every complete card round-tripped unchanged
  through six HTTP pages and MCP search.
• Wheel build, packaged schema generation, import sorting, format checks,
  lint, documentation sync, and whitespace checks completed.

CI and the follow-up Cursor Bugbot review passed on commit
e262d0d8c24a2340325554ddb1efc25bb2633569:
https://github.com/huggingface/OpenEnv/actions/runs/34401634980

An earlier Python 3.12 job missed an unchanged rubric test's 100ms wall-clock
bound. That test and its runtime files match upstream. The target passed
locally alongside the discovery and CLI tests, and one unchanged CI rerun
passed. No timing threshold, assertion or reward logic was changed.

The repository lint hook reformats and checks out modified files; the equivalent
non-mutating formatter/import-sort/lint checks were used instead to preserve the
change set. No assertions were removed and no runtime tests were replaced by
success-shaped fallbacks.

Review focus

Please review the explicit repository profile, publisher namespace contract,
metadata precedence, and the local snapshot publication/consumption boundary.
Finder integrations are separate consumers, not implementation details of the
OpenEnv runtime.

Public companions:

• feat: read-only OpenEnv environment catalog discovery hf-discover#46: independently implemented snapshot reader.
• feat: canonical ARD identifiers and pinned OpenEnv Echo catalog entry github/agentfinder-catalog#38: canonical ARD compatibility and a pinned Echo record.

---

Note

Medium Risk
Large new public library and CLI surface with Git subprocess reads and catalog integrity rules; behavior is read-only metadata and does not execute environments, but incorrect contracts could mislead consumers about licenses or inventory completeness.

Overview
Adds RFC 011 0.1-draft: revision-bound, metadata-only environment discovery separate from AutoEnv runtime loading.

A new openenv.discovery package defines Environment Cards, catalog snapshots (with SHA-256 digests), strict Pydantic invariants, packaged JSON schemas, and a Git-pinned producer that inventories direct-child envs/*/openenv.yaml from tracked trees only—reading manifests, pyproject.toml, README frontmatter, and optional discovery.json without importing environment code.

CLI: openenv catalog build / inspect and top-level openenv discover for lexical search, exact filters, and identifier lookup against an explicitly configured local snapshot (no remote fetch). Incomplete builds remain inspectable but fail load/search lifecycle use; compare_catalogs tracks adds, withdrawals, supersession, and corrections.

Supporting changes: envs/echo_env/discovery.json example, schema generation script, Discovery catalog GitHub Actions artifact job, docs guide, packaging runtime dep, and broad contract/integration tests (symlinks, license precedence, digest tampering, byte-identical rebuilds).

^{Reviewed by Cursor Bugbot for commit e262d0d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[thegovind]

@burtenshaw tagging you for review of the RFC 011 catalog producer and discovery CLI, especially source identity, snapshot completeness, and the declaration-only profile. The independent public consumer is in huggingface/hf-discover#46.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit b1b0ed0. Configure here.}