From 9ac005359035d72008c9d914a6fdc11ef677c8c7 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Tue, 27 Oct 2026 15:07:15 +0000
Subject: [PATCH] Clarify import default field names

---
 conversion.go                  |  4 ++--
 docs/roadmap/implementation.md |  4 ++--
 facade_import_defaults_test.go |  9 ++++++++-
 lifecycle.go                   | 11 ++++++-----
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/conversion.go b/conversion.go
index f78304b..b2feece 100644
--- a/conversion.go
+++ b/conversion.go
@@ -82,8 +82,8 @@ func toEngineOverrides(values []Override) []engine.Override {
 func toEngineImportDefaults(value ImportDefaults) engine.ImportDefaults {
 	return engine.ImportDefaults{
 		Required:  value.Required,
-		Follow:    value.Follow,
-		Hidden:    value.Hidden,
+		Follow:    value.FollowSymlinks,
+		Hidden:    value.IncludeHidden,
 		Recursive: value.Recursive,
 		Pattern:   value.Pattern,
 	}
diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md
index 9e1880d..472a973 100644
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,6 +1,6 @@
 # Pre-v1 Public API Cleanup Implementation Plan
 
-Status: in progress; Stages 1–3 are complete and Stages 4–11 are pending.
+Status: in progress; Stages 1–4 are complete and Stages 5–11 are pending.
 Baseline: `07e4ae5d9236935389e81b207d4a8f00543fafce`.
 Audience: a Luna coding agent executing the stages sequentially.
 
@@ -198,7 +198,7 @@ placement, partial evidence, and detachment retain established behavior.
 
 ## Stage 4 — Make Go Import Defaults Self-Describing
 
-Status: pending. Implements N6.
+Status: complete. Implements N6.
 
 1. Replace root `ImportDefaults.Follow` with `FollowSymlinks` and `Hidden`
    with `IncludeHidden`, preserving `*bool` and the other three fields.
diff --git a/facade_import_defaults_test.go b/facade_import_defaults_test.go
index 276fc38..a9ed835 100644
--- a/facade_import_defaults_test.go
+++ b/facade_import_defaults_test.go
@@ -93,7 +93,8 @@ main: main
 
 func TestImportDefaultsPreserveEmptyPatternAndRequiredness(t *testing.T) {
 	type config struct {
-		Value string `yaml:"value"`
+		Value  string `yaml:"value"`
+		Hidden string `yaml:"hidden"`
 	}
 	directory := t.TempDir()
 	mainPath := writeFacadeImportFile(t, directory, "main.yml", `configkit:
@@ -101,11 +102,17 @@ func TestImportDefaultsPreserveEmptyPatternAndRequiredness(t *testing.T) {
     - dir: snippets
 `)
 	writeFacadeImportFile(t, directory, "snippets/value.cfg", "value: imported\n")
+	writeFacadeImportFile(t, directory, "snippets/.hidden.cfg", "hidden: imported\n")
 
 	unrestricted, err := Load(File(mainPath), Options[config]{Imports: true})
 	if err != nil || unrestricted.Config.Value != "imported" {
 		t.Fatalf("unspecified pattern = %#v, %v", unrestricted, err)
 	}
+	includeHidden := false
+	visibleOnly, err := Load(File(mainPath), Options[config]{Imports: true, ImportDefaults: ImportDefaults{IncludeHidden: &includeHidden}})
+	if err != nil || visibleOnly.Config.Value != "imported" || visibleOnly.Config.Hidden != "" {
+		t.Fatalf("hidden-file default = %#v, %v", visibleOnly, err)
+	}
 	empty, err := Load(File(mainPath), Options[config]{Imports: true, ImportDefaults: ImportDefaults{Pattern: []string{}}})
 	if err != nil || empty.Config.Value != "" {
 		t.Fatalf("empty pattern = %#v, %v", empty, err)
diff --git a/lifecycle.go b/lifecycle.go
index 59383a0..f134fce 100644
--- a/lifecycle.go
+++ b/lifecycle.go
@@ -62,7 +62,8 @@ const (
 // ImportDefaults supplies load-wide defaults for enabled import declarations.
 // Each field applies independently and an explicit declaration value takes
 // precedence. Nil boolean fields are unspecified and leave the library defaults
-// in effect: Required false, Follow true, Hidden true, and Recursive false.
+// in effect: Required false, FollowSymlinks true, IncludeHidden true, and
+// Recursive false.
 // Pattern applies to directory searches; nil leaves filenames unrestricted,
 // while a non-nil empty slice selects none. Defaults apply to main, underlay,
 // and transitive imports, not selected overlays. Load calls snapshot the
@@ -71,10 +72,10 @@ type ImportDefaults struct {
 	// Required defaults absence handling. For path, true requires every named
 	// file; for dir and glob, true requires at least one selected file.
 	Required *bool
-	// Follow controls discovered symbolic links for directory and glob search.
-	Follow *bool
-	// Hidden controls discovery of hidden files and directories.
-	Hidden *bool
+	// FollowSymlinks controls discovered symbolic links for directory and glob search.
+	FollowSymlinks *bool
+	// IncludeHidden controls discovery of hidden files and directories.
+	IncludeHidden *bool
 	// Recursive controls descendant traversal for directory searches.
 	Recursive *bool
 	// Pattern replaces the library's unrestricted filename matching for directory