base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Record alias help and discovery decisions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-19 01:16:50 +00:00
parent 50c54c229e
commit 4b53c96cf3
1 changed files with 29 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/roadmap/aliases.md
View File

@@ -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