okf: allow extensible bundle-root frontmatter for discovery

[LearnerHong]

Summary

This PR updates okf/SPEC.md to make the YAML frontmatter of the bundle-root index.md an extensible metadata container.

It:

• permits producer-defined keys alongside okf_version;
• standardizes optional bundle-level title and description descriptors;
• adds guidance for discovering and selecting among multiple bundles before loading their content;
• clarifies that the Section 11 type rule applies to concepts rather than the bundle-root index; and
• aligns the related language in Sections 12 and 13.

Motivation

OKF already supports progressive disclosure within a bundle through its root index.md. However, a consumer presented with multiple bundles currently has no portable, standardized way to understand what each bundle contains before reading that index body or any concept document.

Extensible root frontmatter provides a general metadata surface, while title and description provide a minimal interoperable convention for pre-load discovery. Producers may add other metadata without requiring a new specification field for every use case, and consumers remain compatible by tolerating unknown keys.

A typical consumption flow is:

1. inspect the available bundle descriptors;
2. select the bundles relevant to the current task;
3. read the selected root index.md;
4. search or traverse concepts; and
5. load full concept content only when needed.

Scope

This proposal is limited to the OKF document format. It does not define:

• purpose, task, or audience routing hints;
• a discovery or retrieval API;
• a separate manifest;
• storage or transport behavior; or
• an agent runtime protocol.

The proposal is orthogonal to the concept-level routing discussion in #96 and #189.

Compatibility and versioning

The new fields are optional. Bundles that omit title and description remain conforming, and consumers must tolerate producer-defined root-frontmatter keys they do not recognize.

This is a backward-compatible addition under Section 12. This draft leaves the document at v0.2 so maintainers can decide whether it should land in v0.2 or a subsequent minor revision.

Addresses #302.

Related: #212, #214.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[LearnerHong]

@libei

Hi @libei, I noticed your recent work on mdcode and OKF bundle round-tripping.

This proposal adds an extensible metadata surface to the bundle-root index for pre-load discovery. Since it may affect how tools preserve and consume root metadata, would you be willing to advise whether you are the right reviewer, or point me to the appropriate maintainer?

No urgency, and I am happy to revise the proposal based on maintainer guidance.

[andrewcrenshaw]

Producer support for this change, with a measured datapoint behind it: this exact ambiguity has been resolved conservatively by four independent producers, each concluding we could not tell from sections 6 and 11 whether anything beside okf_version was legal in root-index frontmatter. Our exporter (the remember wiki compiler at Lexenne, PR #195 / #182) emits okf_version and nothing else for that reason; @jpavley reported the same resolution for civic-records bundles on #212, @johnno100 for a 36-bundle enterprise deployment on #214, and @kaeferboeck for safety-critical automation KBs on #212. Four producers guessing identically at the same gap is the practical case for the one-line MAY.

The title / description descriptors also give the okf_profile declaration discussed on #212 a defined place to live, which is the half that discussion was waiting on.

One compatibility note worth stating in review: producers who resolved conservatively have nothing to migrate - the change is purely permissive - so it costs existing bundles nothing, ours included.