Document application-owned alias contracts

identity.go

@@ -28,7 +28,9 @@ type Streams struct {
 }
 
 // Invocation provides execution context and output streams to a command
-// handler.
+// handler. For command aliases, EnteredPath and CanonicalPath expose the route
+// the caller used and the selected canonical command path. Both omit the
+// executable name, flags, and operands.
 type Invocation struct {
 	// Context carries caller cancellation and request-scoped values.
 	Context context.Context
@@ -39,10 +41,13 @@ type Invocation struct {
 	canonicalPath string
 }
 
-// EnteredPath returns the command path used to invoke the selected command.
-// It is empty for an Invocation that was not created by command execution.
+// EnteredPath returns the command path used to invoke the selected command,
+// excluding the executable name, flags, and operands. It is empty for an
+// Invocation that was not created by command execution.
 func (inv Invocation) EnteredPath() string { return inv.enteredPath }
 
-// CanonicalPath returns the selected command's canonical path.
-// It is empty for an Invocation that was not created by command execution.
+// CanonicalPath returns the selected command's canonical path after resolving
+// aliases, excluding the executable name, flags, and operands. It equals
+// EnteredPath for a direct canonical invocation and is empty for an Invocation
+// that was not created by command execution.
 func (inv Invocation) CanonicalPath() string { return inv.canonicalPath }