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 executable code or configuration behavior changes.

Overview
Adds draft RFC 011 and indexes it under a new Discovery & Distribution section in rfcs/README.md. No runtime, CLI, or manifest changes ship in this PR.

The RFC defines a read-only, metadata-first path to find unfamiliar OpenEnv environments by task: a versioned producer maps authoritative source metadata into ARD entries carrying an experimental application/vnd.openenv.environment-card+json payload, and a reference consumer searches/inspects versioned catalog snapshots while preserving provider, repo URI, environment path, and revision. It explicitly separates discovery from execution (no install, pull, wake, reset/step, or tool calls) and from RFC 008 validation unless a claim is marked validated.

Notable revision choices in the new text: acceptance is inventory/correctness/identity/complete-card/read-only/lifecycle—not a mandatory semantic ranker or 0.10 nDCG@5 gate; basic discovery does not block on RFC 008 reports; requires_explicit_trust is removed; card fields distinguish manifest_spec_version and framework_requirement from protocol guarantees; the Echo example is pinned to public GitHub envs/echo_env at commit b9d8c1f9 with illustrative example.org publication authority.

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