Record alias registration conventions in roadmap

docs/roadmap/aliases.md

@@ -1,7 +1,8 @@
 # Application-owned aliases
 
 Status: command- and flag-alias directions accepted; implementation has not
-started. Public API and remaining routing details are open. This roadmap records
+started. Consumer registration conventions are selected; the installer declaration
+type and remaining routing details are open. This roadmap records
 the target and work needed before implementation.
 
 ## Purpose and ownership
@@ -52,6 +53,44 @@ command path, can be interspersed with operands, and use `--` to terminate
 option parsing. Aliasing preserves the target's grammar and typed binding
 contracts.
 
+## Selected declaration and registration conventions
+
+Commands and aliases use the same installation boundary through `New` and
+`App.Register`. Core validates the complete batch together while retaining
+aliases as separate routing records internally. No separate alias-registration
+API is needed.
+
+Use space-separated strings for command paths, interpreted as sequences of
+command names without shell quoting or expansion. Application-wide flag aliases
+use `FlagAlias`; command-scoped aliases use `FlagAliasFor` with an explicit
+canonical command path. The selected consumer-facing shape is:
+
+```go
+app, err := commandkit.New(
+    identity,
+    ckprompt.Command(suite),
+    commandkit.Alias("list collections", "promptkit list collections"),
+    commandkit.FlagAlias("--hlep", "--help"),
+    commandkit.FlagAliasFor("promptkit show prompt", "--ver", "--version"),
+)
+```
+
+This illustrates planned APIs. The declaration type accepted by the installer
+still needs design; aliases remain routing records rather than fabricated
+canonical command nodes. Later registration uses the same model and validation.
+
+Accept identical duplicate alias mappings as harmless, including when reusable
+helpers contribute them. Identity includes the alias kind, source, target, and
+scope where applicable. Different-target command mappings for the same source
+remain errors; overlap between flag scopes is addressed under OD-6.
+
+Alias support lives entirely in core and works with built-in commands,
+application commands, optional integrations, or any combination. Validation
+uses the commands and flags installed in that application. No integration
+dependency is required for alias support. Core continues to supply help and
+version automatically, including for applications whose other commands are
+entirely application-defined.
+
 ## Selected command-alias behavior
 
 ### Paths and resolution
@@ -95,9 +134,8 @@ transformation, and arbitrary argument rewriting are outside this delivery.
 
 ### Installation and collisions
 
-Provide a small core API for aliases that composes with installation of
+Use the shared declaration and installation conventions above for aliases,
-application and integration commands. The public declaration and registration
+application commands, and integration commands.
-shape remains open; earlier illustrative `Alias` calls are not a settled Go API.
 
 An alias target may already be installed or be supplied in the same installation
 batch. Declaration order within that batch does not affect resolution. Missing
@@ -109,8 +147,8 @@ An alias cannot conflict with or overload a canonical command path. Reject such
 a declaration during installation as invalid application configuration. Apply
 the same protection when later registration adds a canonical command conflicting
 with an existing alias. Reject competing mappings from the same source path to
-different targets; registration order must not select a winner. Whether identical
+different targets; registration order must not select a winner. Identical
-duplicate declarations are accepted remains open.
+duplicate mappings are accepted under the shared registration conventions.
 
 Detailed prefix interactions remain open below. Aliases do not create canonical
 parent groups, merge integration trees, or replace handlers.
@@ -143,7 +181,7 @@ from canonical commands. Group help and discovery details remain to be specified
 
 Applications can declare alternate spellings for canonical flags, including
 `--hlep` mapping to `--help`. Declaring a flag alias should be as simple as
-declaring a command alias; the exact Go API remains open.
+declaring a command alias, using the shared registration conventions above.
 
 Support application-wide mappings and mappings scoped to a canonical command.
 The selected canonical command determines the applicable flag aliases, so a
@@ -207,7 +245,7 @@ target validation, and help presentation remain open below.
 
 ## Work needed from the baseline
 
-1. Settle the public alias API and the open routing details with consumer examples
+1. Finalize the installer declaration type and open routing details with consumer examples
    covering a command shortcut, a synonym inside an integration namespace, and
    a group shortcut, an application-wide help flag alias, and a command-scoped
    flag alias reached through a command shortcut.
@@ -240,12 +278,14 @@ details are still to be settled.
 
 ## Open Decisions
 
-### OD-1: Public declaration and registration API
+### OD-1: Installer declaration type and composition details
 
-What are the exact command- and flag-alias declaration, path representation, and
+The shared installation API, path strings, explicit flag scopes, identical
-installation signatures? How do alias declarations compose with groups, reusable
+duplicate handling, and core-only availability are selected above. What public
-declarations, and later `App.Register` calls? Are identical duplicate declarations
+declaration type lets `New` and `App.Register` accept commands and aliases
-accepted?
+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-2: Prefix interactions and canonical reachability