Settle the direct overlay catalog format

docs/roadmap/overlays.md

@@ -1,7 +1,8 @@
 # Single-file named overlays
 
-Status: proposal; strict composition between the two forms is accepted. Remaining
+Status: strict composition between the two forms and direct catalog structure
-decisions are listed below. Not implemented. Implementation baseline: `ce6005c`.
+are settled. Remaining decisions are listed below. Not implemented.
+Implementation baseline: `ce6005c`.
 
 ## Purpose
 
@@ -15,6 +16,12 @@ contributions, strictly composes them, and applies the resulting overlay once.
 This follows [ADR 0001](../adr/0001-separate-composition-and-overlay.md): peer
 composition and intentional precedence remain separate operations.
 
+This roadmap extends file-based selected overlays. The selected contributions
+compose as peers at the overlay stage; overlay definitions do not acquire
+underlay or main-input precedence tiers. A configuration-wide catalog populated
+through inline `config.overlays`, ordinary imports, or application underlays is
+outside this feature's scope. No new application or source-control key is reserved.
+
 ## Current baseline
 
 The [selected-overlay contract](../config.md#selected-overlays) currently loads
@@ -40,10 +47,11 @@ cleanup already cover the individual-file form.
 
 ### File layout and selection
 
-The proposed catalog is a mapping from overlay names directly to overlay bodies:
+The catalog is a mapping from overlay names directly to overlay bodies, without
+an enclosing `overlays` key:
 
 ```yaml
-# overlays.yml — proposed format
+# overlays.yml — planned format
 production:
   service:
     workers: 8
@@ -73,8 +81,8 @@ service:
 If the individual file instead also defines `service.workers: 12`, ordinary
 strict-composition conflict rules apply. File order grants no precedence.
 The other catalog entries do not contribute to the selected configuration.
-The exact catalog structure and its validation boundary remain in OD-1 through
+OD-1 settles this catalog structure. Source-version/control scope and the
-OD-3; this example illustrates the recommended structure.
+validation boundary remain in OD-2 and OD-3.
 
 Use the same lookup directory for the catalog and the existing `overlays/`
 directory. Preserve ordinary versus layered lookup semantics, explicit context
@@ -187,20 +195,22 @@ benchmark campaign or release gate is required. Completion means applications
 can select one named overlay from either or both forms with the same composition,
 precedence, and inspection model.
 
+## Settled Decisions
+
+### OD-1: Catalog structure — settled
+
+Use the direct name-to-body mapping illustrated above, with no enclosing
+`overlays` mapping. The filename identifies the document's role; each named body
+remains recognizable as an individual overlay file's contents. The top-level
+mapping is a selection container and is not passed to application decoding.
+Overlay names retain existing spelling and selection rules, including empty
+selection and exact lowercase `default` meaning no overlay.
+
+This settles the storage structure within the narrower file-based feature.
+Source-version declarations and document controls remain subject to OD-2.
+
 ## Open Decisions
 
-### OD-1: Catalog structure
-
-**Recommendation:** use the direct name-to-body mapping illustrated above.
-It adds only one enclosing mapping and keeps each body recognizable as an
-ordinary overlay. The catalog wrapper is a selection container, not an application
-document; overlay names retain existing spelling and selection rules. The special
-`default` selection continues to mean no overlay.
-
-**Alternative:** wrap entries under an `overlays` key, leaving space for catalog
-metadata. This gives file-level headers an explicit home, but adds boilerplate
-and another reserved structure before a need for catalog metadata is established.
-
 ### OD-2: Source-version declarations and document controls
 
 **Recommendation:** treat each selected body as the overlay's logical document
@@ -218,9 +228,10 @@ physical document from the selected logical overlay in version processing and
 inspection; it must not silently change source-version semantics for other inputs.
 
 **Alternative:** declare the version and shared controls once at catalog level,
-with entries inheriting them. This reduces repeated headers but needs the wrapper
+with entries inheriting them. This reduces repeated headers but needs a metadata
-from OD-1 or another metadata convention, plus rules for shared versus per-entry
+convention alongside the named entries, including rules for collisions with overlay
-controls. It also makes a standalone overlay body differ from its catalog form.
+names and shared versus per-entry controls. It must respect OD-1's direct mapping
+and also makes a standalone overlay body differ from its catalog form.
 
 ### OD-3: Validation of unselected bodies