fix(docs): list visible flag aliases

PLAN.md

@@ -528,6 +528,9 @@ Groups are the opposite case: `Command::get_groups`, `ArgGroup::get_args` and
       names automatically, honoring `NO_COLOR` and `CLICOLOR_FORCE`; explicit
       plain/coloured rendering stays available for tests and generated artifacts.
       clap's arbitrary `Command::styles` palette is intentionally not reproduced.
+- [x] **Visible aliases in generated references.** Markdown and JSON reference
+      models list every visible short and long spelling while interactive help
+      retains its compact aligned first-pair layout; hidden aliases stay hidden.
 - [ ] **`term_width` / `max_term_width`** — we wrap to `COLUMNS` and take no
       instruction about it.
 - [x] **The granular hides** — `hide_default_value`, `hide_env`, `hide_env_values`,

lib/src/docs/markdown/cmd.rs

@@ -258,4 +258,20 @@ cmd "sub" help="a subcommand"
         - [`mycli sub`](/sub.md)
         ");
     }
+
+    #[test]
+    fn generated_reference_lists_every_visible_flag_alias() {
+        let spec: Spec = r#"
+bin "mycli"
+flag "-t -f --tail --follow" help="Follow output"
+"#
+        .parse()
+        .unwrap();
+        let ctx = MarkdownRenderer::new(spec.clone()).with_multi(true);
+        let rendered = ctx.render_cmd(&spec.cmd).unwrap();
+        assert!(
+            rendered.contains("### `-t -f --tail --follow`"),
+            "{rendered}"
+        );
+    }
 }

lib/src/docs/models.rs

@@ -623,12 +623,43 @@ fn column_usage(flag: &crate::SpecFlag) -> String {
     format!("{short:<SHORT_COL$}{after}")
 }
 
+/// Every visible spelling for generated reference documentation.
+///
+/// Interactive help keeps the compact first short/long pair in its aligned
+/// column, while a reference page should document aliases users can type.
+fn reference_usage(flag: &crate::SpecFlag) -> String {
+    let mut forms: Vec<String> = flag
+        .short
+        .iter()
+        .filter(|short| !flag.hidden_short_aliases.contains(short))
+        .map(|short| format!("-{short}"))
+        .chain(
+            flag.long
+                .iter()
+                .filter(|long| !flag.hidden_aliases.contains(long))
+                .map(|long| format!("--{long}")),
+        )
+        .collect();
+    if flag.usage.trim().starts_with(&format!("{}:", flag.name)) {
+        forms.insert(0, format!("{}:", flag.name));
+    }
+    let mut usage = forms.join(" ");
+    if flag.var {
+        usage.push('…');
+    }
+    if let Some(arg) = &flag.arg {
+        usage.push(' ');
+        usage.push_str(&arg.usage());
+    }
+    usage
+}
+
 impl From<&crate::SpecFlag> for SpecFlag {
     fn from(flag: &crate::SpecFlag) -> Self {
         Self {
             name: flag.name.clone(),
             effect: flag.effect,
-            usage: flag.usage.clone(),
+            usage: reference_usage(flag),
             display_usage: column_usage(flag),
             help: said(&flag.help),
             help_long: flag.help_long.clone(),