diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index c58ba60..f4035e7 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -225,8 +225,33 @@ scriptorium list collections --help ``` Alias help describes the canonical target's inputs using the alias invocation -path and identifies the canonical command. Root help presents aliases separately -from canonical commands. Group help and discovery details remain to be specified. +path and identifies the canonical command. Root help lists explicitly declared +command aliases separately from canonical commands, showing their resolved +canonical targets. Ordinary help need not show intermediate chain mappings or +enumerate every route reachable through group shortcuts. + +Group help includes relevant aliases separately from canonical children. For +example, `help promptkit test` shows `full → promptkit test all`. Help reached +through a group alias uses that spelling in usage examples and presents the +routes available through it, including applicable aliases beneath the target. +Account for more-specific mappings so displayed destinations match routing. + +Provide discovery help for alias-only prefixes. If `list collections` and +`list prompts` are declared without a canonical `list` group, both `help list` +and `list --help` display the available routes. This help view is derived from +alias declarations and creates no canonical group or namespace ownership. +Bare `list` reports an incomplete command and points to that help. + +Usage errors use the entered path and identify the canonical target when one +has been resolved, while preserving the canonical command's diagnostic content: + +```text +Usage: scriptorium list collections [flags] +Alias for: scriptorium promptkit list collections +``` + +If resolution fails before identifying a target, report the entered route +without assigning a canonical identity. ## Selected flag-alias behavior @@ -341,18 +366,11 @@ together? How do collections of reusable declarations and group composition interact with application-root alias paths? What exact whitespace parsing and path validation rules accompany the selected string representation? -### OD-4: Help and discovery - -How are aliases listed, grouped, and described in help? What happens when an -operator requests a parent of an alias path that has no canonical group? How -does group-alias help present descendants? How are entered and canonical paths -shown in usage errors? - ### OD-5: Invocation identity Does the public invocation API expose entered and canonical command paths? -What identity is retained through a chain, and how is it represented for help -and diagnostic presentation? +What identity is retained through a chain, and how is it represented in that +API? Help and diagnostic presentation are selected above. ### OD-6: Flag alias scope and composition