RFC 011: ARD-backed catalog discovery for portable environments

[thegovind]

Summary

The goal is to let a user find an unfamiliar OpenEnv environment by task, inspect its source and limitations, and preserve the exact subject being selected without running it.

ARD-OPENENV.mp4

RFC 011 now proposes a versioned metadata producer and reference consumer as the first implementation milestone. OpenEnv owns the Environment Card; ARD carries it as an extension. Existing authored metadata is reused before introducing duplicate fields.

flowchart LR
  Source["Authoritative metadata"] --> Producer["Versioned producer"]
  Producer --> Catalog["Scoped ARD catalog"]
  Catalog --> Consumer["Read-only consumer"]
  Consumer --> Choice["Source, path, revision"]
  Catalog -.-> Ranking["Optional ranking"]
  Ranking -.-> Consumer

Loading

Companion generic diagnostic draft: ards-project/ard-spec#85. The PRs are independent. ARD already permits the OpenEnv extension type.

What changed in this revision

• Basic discovery is assessed through inventory accounting, useful metadata, identity, complete-card handling, read-only behavior, and update/removal. A deterministic lexical baseline can be a valid outcome.
• Removed the mandatory 0.10 nDCG@5 improvement and benchmark-before-implementation gate. Optional ranking changes retain separate, preregistered quality/cost/latency evaluation.
• Basic unvalidated discovery no longer waits for RFC 008 reports. Validated claims still require the appropriate stable, revision-bound evidence.
• Defined the initial producer, snapshot, and complete-result contract, including explicit incomplete outcomes rather than guessed URLs or fields.
• A second source is required before a strong portability claim, not before a useful scoped first-source milestone.
• Removed the publisher-controlled execution-policy boolean. A legacy false value cannot lower local approval requirements.
• Added the monorepo environment path and replaced the ambiguous compatibility marker with manifest_spec_version and a source-declared framework_requirement, without inferring a protocol version.
• Replaced the Echo example with the public GitHub repository, full commit b9d8c1f953e0c3e0bbee2f3f6f6c73d8eae61f5f, envs/echo_env locator, and source-supported BSD-3-Clause license evidence.

The sample's publication authority is reserved example.org; it does not claim that GitHub or Hugging Face published or verified the card.

Scope

Only rfcs/011-ard-catalog-discovery.md and rfcs/README.md change relative to upstream main.

This remains a draft, docs-only proposal. It adds no registry, adapter, command, runtime endpoint, dependency, or execution path. No candidate install/import, image pull, wake, reset, step, or tool invocation belongs in discovery.

Review decisions

Before the first producer-consumer milestone, agree on the maintained source and publication owner, schema/profile location, source/revision and record identity, metadata precedence, and independently chosen selection tasks.

Later URL retrieval, second-provider profiles, validated evidence, private credentials, and richer interfaces retain explicit stage-specific decisions. The RFC 008 restoration state is documented without treating its older CLI output as equivalent evidence.

Test plan

• Check the complete sample against the ARD entry schema and its source/revision/path invariants.
• Confirm the license and framework requirement against the pinned public GitHub files.
• Render the RFC and PR-description Mermaid diagrams.
• Check local Markdown links, documentation sync, and whitespace.
• Confirm the branch includes current upstream main and both PRs remain drafts.

Type of change

Documentation and RFC revision only. The first implementation follows review of this proposal; it is not shipped here.

---

Note

Low Risk
Documentation-only RFC and README index update; no code, APIs, or runtime behavior changes.

Overview
Adds draft RFC 011 proposing read-only, task-oriented environment discovery before execution: a versioned metadata producer, scoped ARD catalog, and reference consumer carrying an experimental Environment Card (application/vnd.openenv.environment-card+json) with explicit source URI, monorepo path, and revision identity.

The revision tightens milestone and acceptance rules: inventory accounting, complete-card vs honest incomplete results, read-only behavior, and lifecycle updates/removals; a lexical baseline can ship without beating a ranker. It drops the mandatory nDCG@5 gate and decouples basic discovery from RFC 008 validation (validated claims still need revision-bound evidence). Card semantics now separate manifest_spec_version and framework_requirement, remove publisher requires_explicit_trust, and replace the sample with a GitHub echo_env ARD entry at commit b9d8c1f9.

rfcs/README.md gains a Discovery & Distribution index entry for RFC 011. No runtime, CLI, or schema implementation in this PR.

^{Reviewed by Cursor Bugbot for commit 97c5791. 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.

[burtenshaw]

This looks good, and we can merge. In a future PR, it would be good to: also add the example client usage here.