Clarify collection contracts and migration docs

requirements.go

@@ -8,13 +8,16 @@ import (
 )
 
 // RequirementInspectionRequest selects a prompt and supplies caller context
-// for requirement discovery. It requires no artifact bindings or credentials.
+// for requirement discovery. A namespace-scoped engine view qualifies
+// slashless caller IDs; otherwise IDs select exact configured resources. It
+// requires no artifact bindings or credentials.
 type RequirementInspectionRequest struct {
-	// PromptID is the exact, case-sensitive configured prompt ID.
+	// PromptID is the exact, case-sensitive configured prompt ID, or a slashless
+	// caller ID qualified by a namespace-scoped engine view.
 	PromptID string
-	// ProfileID selects the exact effective profile identity. If empty, the
-	// prompt's default profile is used; the profile need not be ready for
-	// execution.
+	// ProfileID selects the exact effective profile identity, or a slashless
+	// caller ID qualified by a namespace-scoped view. If empty, the prompt's
+	// default profile is used; the profile need not be ready for execution.
 	ProfileID string
 	// Vars supplies string values for caller-variable lookups and simple
 	// conditions. Presence is determined by exact map key, including an empty
@@ -116,8 +119,9 @@ type RequirementIssue struct {
 // prompt context. Input and variable entries are sorted by exact name. Issues
 // are deduplicated by code and associated names, then sorted by that tuple.
 // Their descriptions and entry explanations are safe summaries, not
-// machine-readable details. PromptVersion is caller-owned: nil means no label
-// was declared; a non-nil empty string is explicit.
+// machine-readable details. PromptVersion is caller-owned descriptive metadata,
+// not a selection key: nil means no label was declared; a non-nil empty string
+// is explicit.
 //
 // Complete describes the supported analysis's discovery coverage, not whether
 // requirements are supplied, templates will render, artifacts or schemas are
@@ -129,8 +133,9 @@ type RequirementIssue struct {
 type RequirementInspection struct {
 	// PromptID is the selected exact prompt ID.
 	PromptID string
-	// PromptVersion is the selected definition's descriptive version label. Nil
-	// means no label was declared; a non-nil empty string is an explicit label.
+	// PromptVersion is the selected definition's descriptive version label and
+	// never participates in prompt selection. Nil means no label was declared; a
+	// non-nil empty string is an explicit label.
 	PromptVersion *string
 	// ProfileID is the selected profile identity; it does not indicate
 	// execution readiness.
@@ -149,12 +154,13 @@ type RequirementInspection struct {
 }
 
 // InspectRequirements discovers inputs and caller variables for one selected
-// prompt before its input artifacts exist. It uses exact, case-sensitive
-// prompt selection and requires a profile ID either in the request or the
-// selected prompt's default. The selected profile establishes identity only;
-// it need not be execution-ready. A normalized nonblank SessionID bypasses the
-// captured session template. Vars are copied before analysis, and returned
-// slices and metadata pointers belong to the caller.
+// prompt before its input artifacts exist. It selects an exact, case-sensitive
+// prompt ID; a namespace-scoped view qualifies slashless caller IDs before
+// lookup. A profile ID is required either in the request or the selected
+// prompt's default. The selected profile establishes identity only; it need
+// not be execution-ready. A normalized nonblank SessionID bypasses the captured
+// session template. Vars are copied before analysis, and returned slices and
+// metadata pointers belong to the caller.
 //
 // Discovery recognizes literal input names, direct caller-map keys, literal-
 // key root-map lookups, simple caller-derived input names, and if/with