Document main-relative companion loading

layered.go

@@ -19,7 +19,9 @@ type Input struct {
 	PlacementMode PlacementMode
 	Imports       bool
 	Filesystem    *FilesystemContext
-	MainRelative  *MainRelativeContext
+	// MainRelative binds a non-file underlay to the main input's context when
+	// Filesystem is nil. It does not enable imports.
+	MainRelative *MainRelativeContext
 }
 
 // MainRelativeContext selects the main input's resolved context for an underlay.
@@ -37,8 +39,9 @@ func MainRelative() *MainRelativeContext { return &MainRelativeContext{} }
 type Underlay struct{ Inputs []Input }
 
 // LayeredOptions selects lower-priority tiers and final application rules.
-// An active Overlay requires an explicit OverlayFilesystem; an inactive overlay
-// ignores it. Overrides remain explicit CLI records, not general mappings.
+// An active Overlay uses OverlayFilesystem, then the main input's resolved
+// context, then OverlayFallback. An inactive overlay ignores both contexts.
+// Overrides remain explicit CLI records, not general mappings.
 // SourceVersionMode applies one declaration policy to main, underlay, import,
 // and selected overlay documents. Enabled modes interpret the version path
 // source-locally, consume accepted non-main declarations, and protect main's
@@ -53,8 +56,9 @@ type LayeredOptions[T any] struct {
 	Underlays         []Underlay
 	Overlay           string
 	OverlayFilesystem *FilesystemContext
-	OverlayFallback   *FilesystemContext
-	Overrides         []Override
+	// OverlayFallback supplies a context if the main has no usable context.
+	OverlayFallback *FilesystemContext
+	Overrides       []Override
 }
 
 // LoadLayered acquires the main input first and strictly composes enabled