Naming Aliases

mandatory

Behavioral guidance for *when* to create an alias for a Koder Stack component, and *when not to*. Aliases are the compact/colloquial form of reference (kflow, kdrafts, kterm) registered in meta/docs/stack/registries/component-names.md. Mechanism (regex, uniqueness, max 3) lives in specs/naming/forms.kmd; this policy decides the human judgement of which components deserve one.

Policy — Naming Aliases

Aliases (kflow, khub, kdrafts) capture how a component is *poken, typed in a terminal, or referred to in shorthand* They are not a mechanical k-prefix rule — they exist when the bare name causes friction or ambiguity, and they are absent when the bare name is already distinctive.

This policy decides when an alias is justified. The how (regex, uniqueness, max count) is in specs/naming/forms.kmd.

1. Three questions before adding an alias

For any component, before declaring an alias, answer:

*s the bare name a common English word that may collide with
non-Koder context?*Examples: Flow, Hub, Talk, Term, Jet, Eye, Drafts, Sites. → Likely needs alias.

*oes the binary CLI name collide with an existing command in
$PATH on a standard Linux system?*Examples: term (close to shell builtin behavior), jet (npm packages, AWS jets), eye (some Python libs). → Definitely needs alias.

*s the spoken/written form ambiguous when said aloud or written in
a sentence?*"Open flow" — flow the product or a generic flow? → Needs alias. "Open koda" — unambiguous; Koda is a Koder-specific word. → No alias needed.

If *ll three are "no"* do not create an alias. The bare name does the job; an extra alias is dead weight in the registry.

2. When to create an alias

Situation	Decision
Bare name is common English word + likely conversational ambiguity	Create alias (typically `k<bare>` compacted)
Bare name collides with `$PATH` binaries	Create alias (mandatory, binary needs it)
Component is a CLI tool that users will type	Create alias if bare is ambiguous; skip if distinctive
Component is a library/SDK consumed by other code (not typed by users)	Skip alias unless docs/conversation routinely produce ambiguity
Component is internal infrastructure (daemons, build scripts)	Skip alias — no user-facing reference

3. When to NOT create an alias

Situation	Reason
Bare name already starts with K and is distinctive (Koda, Kortex, Kompass, Krono, Krux)	`k`-prefixing would yield `kkoda` etc. — wrong. Bare is already compact and distinct.
Bare name is an acronym/abbreviation (RFCs, KDS)	Already compact; alias adds nothing
Component is `type=umbrella`	Umbrellas are conceptual groupings, not deployable. Alias on umbrella is advisory only and usually unnecessary
Adding the alias would create a `$PATH` collision with another Koder binary	Use a different alias or omit

4. Alias form conventions (not enforced — guidance)

The spec enforces the regex ^[a-z][a-z0-9]*$ and uniqueness. Within those constraints, prefer:

*kbare-compacted-lowercase`*as the default form when the bare
name is a common English word. Examples: kflow, khub, ktalk, kterm, kjet, keye, kdrafts.

*rop internal hyphens*when compacting multi-word bare names.
Koder Web Kit → bare Web Kit → alias candidate kwebkit (not kweb-kit, since R6.3 forbids hyphens in aliases).

*f k<bare> is awkward or already taken* propose an alternative
compact form and document the reason in aliases_reason. Examples: if kjet were taken by another component, the Jet product might register kjt or koderjet — the spec is agnostic; only uniqueness matters.

*ultiple aliases*are allowed (max 3) when distinct contexts
warrant. Example: a product might have kflow for CLI binary and kf for muscle-memory shorthand if both are widely used. Each alias needs its own aliases_reason.

5. Revoking an alias

Aliases can be removed via PR to the registry when:

The alias is unused in practice (no docs, no CLI binary, no chat history).
The component is deprecated/archived.
A clearer alias replaces it.

Removal is non-breaking only if the alias was never shipped as a binary name. If a binary was shipped with the alias, the deprecation requires a transition window per specs/releases/packaging.kmd.

6. PR checklist when changing the registry

Before opening a PR that adds, modifies, or removes aliases:

[ ] Run koder-spec-audit naming locally; all T1-T11 pass.
[ ] For each new alias, confirm answers to the *hree Questions*
(§1) and document in the commit message.
[ ] For each removed alias, confirm it is not in use as a current
binary name.
[ ] Confirm aliases_reason is populated for every entry in
aliases.

The Gitea workflow .gitea/workflows/audit-naming.yml enforces T1-T11 on the server. This checklist covers the judgement calls the audit cannot make.