feat(ui/shell): declutter and space out the slash command menu

Add a blank gap line between the input row and the slash command popup,
drop the redundant [command]/[shell] tag (keeping the distinguishing
[skill]/[flow] tags), and add a persistent footer legend set off by its
own separator line. When the list overflows, the footer folds in a
'+N more' count instead of silently hiding entries; the menu height
adapts to the terminal and is capped to leave room for the chrome rows.

Author: elkaix

CHANGELOG.md

@@ -24,6 +24,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
 - **Login selector polish.** Configured `/login` providers render with distinct success/state styling; the background working indicator uses the braille spinner, and working tips wrap with a hanging indent under the verb.
 - **Scratch cleanup on exit.** Sessions that end via an exception now clean up their scratch files instead of orphaning them.
 - **Readable diff context.** Unchanged context lines in file-edit diff snippets now render in the normal body-text color instead of muted grey, so edited-file previews are easier to read; added/removed lines are unchanged.
+- **Cleaner slash command menu.** The slash command popup now has a blank line separating it from the input row, drops the repetitive `[command]`/`[shell]` tag (keeping the distinguishing `[skill]`/`[flow]` ones), and gains a persistent footer (`Enter to select · ↑/↓ to navigate · Esc to cancel`) set off by its own separator line. When the list scrolls, the footer folds in a `+N more` count instead of silently hiding entries, and the menu height adapts to the terminal.
 
 ## 0.42.0 (2026-06-12)
 

src/pythinker_code/ui/shell/prompt.py

@@ -467,14 +467,21 @@ def _display_meta(self, cmd: SlashCommand[Any]) -> str:
         if not self._annotate_meta:
             return cmd.description
 
+        # Only surface a kind tag when it distinguishes the entry from a plain
+        # command. Skills and flows are interleaved with commands in the agent
+        # menu, so their tag carries information; the generic command/shell scope
+        # is already obvious from the menu itself, so tagging every row is noise.
         if cmd.name.startswith("skill:"):
-            kind = "skill"
+            kind: str | None = "skill"
         elif cmd.name.startswith("flow:"):
             kind = "flow"
         else:
-            kind = self._command_scope
+            kind = None
 
-        parts = [f"[{kind}]", cmd.description]
+        parts: list[str] = []
+        if kind is not None:
+            parts.append(f"[{kind}]")
+        parts.append(cmd.description)
         if cmd.aliases:
             parts.append(f"aliases: {', '.join('/' + alias for alias in cmd.aliases)}")
         return "  ".join(part for part in parts if part)
@@ -851,6 +858,14 @@ class SlashCommandMenuControl(UIControl):
     """Render slash command completions as a full-width menu that matches the shell UI."""
 
     _MAX_EXPANDED_META_LINES = 3
+    # One blank line is reserved above the list as breathing room from the input
+    # row, so the menu reads as its own region rather than crowding what's typed.
+    _GAP_LINES = 1
+    # A persistent footer block at the bottom: a blank separator line plus the
+    # navigation legend (which folds in the overflow count when the list scrolls).
+    # The separator gives the legend the same breathing room as the top gap.
+    _FOOTER_LINES = 2
+    _FOOTER_LEGEND = "Enter to select · ↑/↓ to navigate · Esc to cancel"
 
     def __init__(
         self,
@@ -881,19 +896,27 @@ def preferred_height(
         if complete_state is None:
             return 0
         completions = complete_state.completions
+        if not completions:
+            return 0
         selected_index = complete_state.complete_index
         if selected_index is None:
-            return min(max_available_height, len(completions))
-        menu_width = max(0, width - self._left_padding())
-        marker_width = 2
-        command_width = self._command_column_width(completions, menu_width, marker_width)
-        gap_width = 3 if menu_width > command_width + 6 else 1
-        meta_width = max(0, menu_width - marker_width - command_width - gap_width)
-        selected_meta_lines = self._selected_meta_lines(
-            completions[selected_index].display_meta_text,
-            meta_width,
-        )
-        return min(max_available_height, len(completions) + len(selected_meta_lines) - 1)
+            content_height = len(completions)
+        else:
+            menu_width = max(0, width - self._left_padding())
+            marker_width = 2
+            command_width = self._command_column_width(completions, menu_width, marker_width)
+            gap_width = 3 if menu_width > command_width + 6 else 1
+            meta_width = max(0, menu_width - marker_width - command_width - gap_width)
+            selected_meta_lines = self._selected_meta_lines(
+                completions[selected_index].display_meta_text,
+                meta_width,
+            )
+            content_height = (len(completions) - 1) + len(selected_meta_lines)
+        # Reserve the gap line above the list and the footer line below it. When
+        # the list is taller than the space the window allows, the window caps the
+        # height and create_content lays the list out within whatever rows remain.
+        chrome = self._GAP_LINES + self._FOOTER_LINES
+        return min(max_available_height, content_height + chrome)
 
     def create_content(self, width: int, height: int) -> UIContent:
         app = get_app_or_none()
@@ -905,7 +928,6 @@ def create_content(self, width: int, height: int) -> UIContent:
 
         completions = complete_state.completions
         selected_index = complete_state.complete_index
-        available_rows = max(1, height)
         match_prefix_len = self._match_prefix_len(app)
 
         menu_width = max(0, width - self._left_padding())
@@ -914,16 +936,21 @@ def create_content(self, width: int, height: int) -> UIContent:
         gap_width = 3 if menu_width > command_width + 6 else 1
         meta_width = max(0, menu_width - marker_width - command_width - gap_width)
 
-        rendered_lines: list[FormattedText] = []
-        selected_line_index = 0
+        total_rows = max(1, height)
+        # The gap line above the list and the footer line below it are always
+        # present, so the list itself lays out within the remaining rows.
+        item_rows = max(1, total_rows - self._GAP_LINES - self._FOOTER_LINES)
+
+        rendered_lines: list[FormattedText] = [self._blank_line()]
+        cursor_y = 0
 
         if selected_index is None:
             # Pre-highlight index 0 even before the user navigates: pressing
             # Enter accepts the first completion, so the visual state should
             # match that behavior. Without this the menu looks ambiguous (no
             # row highlighted) but Enter still commits the top row.
-            end = min(len(completions) - 1, available_rows - 1)
-            for index in range(0, end + 1):
+            shown = min(len(completions), item_rows)
+            for index in range(shown):
                 rendered_lines.append(
                     self._render_single_line_item(
                         width=width,
@@ -936,62 +963,83 @@ def create_content(self, width: int, height: int) -> UIContent:
                         match_prefix_len=match_prefix_len,
                     )
                 )
-
-            return UIContent(
-                get_line=lambda i: rendered_lines[i],
-                line_count=len(rendered_lines),
-                cursor_position=Point(x=0, y=0),
+            cursor_y = 1 if shown else 0
+            hidden = len(completions) - shown
+        else:
+            selected_meta_lines = self._selected_meta_lines(
+                completions[selected_index].display_meta_text,
+                meta_width,
             )
-
-        selected_meta_lines = self._selected_meta_lines(
-            completions[selected_index].display_meta_text,
-            meta_width,
-        )
-        start, end = self._visible_window_bounds(
-            completion_count=len(completions),
-            selected_index=selected_index,
-            available_rows=available_rows,
-            selected_item_height=len(selected_meta_lines),
-        )
-        selected_line_index = 0
-
-        for index in range(start, end + 1):
-            completion = completions[index]
-            if index == selected_index:
-                selected_line_index = len(rendered_lines)
-                rendered_lines.extend(
-                    self._render_selected_item_lines(
+            start, end = self._visible_window_bounds(
+                completion_count=len(completions),
+                selected_index=selected_index,
+                available_rows=item_rows,
+                selected_item_height=len(selected_meta_lines),
+            )
+            for index in range(start, end + 1):
+                completion = completions[index]
+                if index == selected_index:
+                    cursor_y = len(rendered_lines)
+                    rendered_lines.extend(
+                        self._render_selected_item_lines(
+                            width=width,
+                            completion=completion,
+                            marker_width=marker_width,
+                            command_width=command_width,
+                            meta_width=meta_width,
+                            gap_width=gap_width,
+                            meta_lines=selected_meta_lines,
+                            match_prefix_len=match_prefix_len,
+                        )
+                    )
+                    continue
+                rendered_lines.append(
+                    self._render_single_line_item(
                         width=width,
                         completion=completion,
                         marker_width=marker_width,
                         command_width=command_width,
                         meta_width=meta_width,
                         gap_width=gap_width,
-                        meta_lines=selected_meta_lines,
+                        is_current=False,
                         match_prefix_len=match_prefix_len,
                     )
                 )
-                continue
+            hidden = len(completions) - (end - start + 1)
 
-            rendered_lines.append(
-                self._render_single_line_item(
-                    width=width,
-                    completion=completion,
-                    marker_width=marker_width,
-                    command_width=command_width,
-                    meta_width=meta_width,
-                    gap_width=gap_width,
-                    is_current=False,
-                    match_prefix_len=match_prefix_len,
-                )
+        rendered_lines.append(self._blank_line())
+        rendered_lines.append(
+            self._render_footer_line(
+                width=width, marker_width=marker_width, hidden_count=max(0, hidden)
             )
-
+        )
         return UIContent(
             get_line=lambda i: rendered_lines[i],
             line_count=len(rendered_lines),
-            cursor_position=Point(x=0, y=selected_line_index),
+            cursor_position=Point(x=0, y=cursor_y),
         )
 
+    def _blank_line(self) -> FormattedText:
+        return FormattedText([("class:slash-completion-menu", "")])
+
+    def _render_footer_line(
+        self, *, width: int, marker_width: int, hidden_count: int
+    ) -> FormattedText:
+        # Persistent navigation legend, rendered in the dim meta style and aligned
+        # under the command column. When the list scrolled, the count of hidden
+        # entries leads so it survives truncation on narrow terminals.
+        indent = self._left_padding() + marker_width
+        text = self._FOOTER_LEGEND
+        if hidden_count > 0:
+            text = f"+{hidden_count} more · {text}"
+        body = _truncate_to_width(text, max(0, width - indent))
+        trailing = max(0, width - indent - get_cwidth(body))
+        fragments: FormattedText = FormattedText()
+        fragments.append(("class:slash-completion-menu", " " * indent))
+        fragments.append(("class:slash-completion-menu.meta", body))
+        fragments.append(("class:slash-completion-menu", " " * trailing))
+        return fragments
+
     def _match_prefix_len(self, app: Any) -> int:
         document = getattr(getattr(app, "current_buffer", None), "document", None)
         if not isinstance(document, Document):
@@ -2637,7 +2685,10 @@ def _install_slash_completion_menu(self) -> None:
             Window(
                 content=self._slash_menu_control,
                 dont_extend_height=True,
-                height=Dimension(max=10),
+                # Cap leaves room for the gap + separator + footer chrome (3 rows)
+                # while still showing ~9 commands; preferred_height clamps to the
+                # terminal's available height so it never overflows a short window.
+                height=Dimension(max=12),
                 style="class:slash-completion-menu",
             ),
             filter=has_completions & slash_completion_filter,

tests/ui_and_conv/test_prompt_tips.py

@@ -1385,7 +1385,8 @@ def test_slash_menu_highlights_typed_command_prefix(monkeypatch: Any) -> None:
     )
 
     content = SlashCommandMenuControl(left_padding=lambda: 0).create_content(width=60, height=5)
-    line = content.get_line(0)
+    # Line 0 is the blank gap row; the first command renders on line 1.
+    line = content.get_line(1)
 
     assert "".join(text for _, text, *_ in line).lstrip().startswith("❯ /model")
     highlighted = [(style, text) for style, text, *_ in line if "command.match" in style]

tests/ui_and_conv/test_slash_completer.py

@@ -248,7 +248,9 @@ def test_completion_display_uses_canonical_command_name():
     assert completions[0].display_meta_text == "help command"
 
 
-def test_annotated_completion_meta_includes_kind_and_aliases():
+def test_annotated_command_meta_drops_generic_tag_but_keeps_aliases():
+    """Plain commands no longer carry a redundant scope tag in the menu; the
+    description and aliases remain so the row stays informative."""
     completer = SlashCommandCompleter(
         [_make_command("help", aliases=["h", "?"])],
         annotate_meta=True,
@@ -258,7 +260,9 @@ def test_annotated_completion_meta_includes_kind_and_aliases():
     completions = _completions(completer, "/h")
 
     assert len(completions) == 1
-    assert completions[0].display_meta_text == "[shell]  help command  aliases: /h, /?"
+    assert completions[0].display_meta_text == "help command  aliases: /h, /?"
+    assert "[shell]" not in completions[0].display_meta_text
+    assert "[command]" not in completions[0].display_meta_text
 
 
 def test_annotated_skill_completion_uses_skill_kind():
@@ -394,13 +398,88 @@ def test_slash_menu_preselects_first_item_when_index_unset(monkeypatch):
         "".join(fragment[1] for fragment in content.get_line(i)) for i in range(content.line_count)
     ]
 
-    assert content.line_count == len(completions)
-    assert content.cursor_position.y == 0
-    # First row is highlighted, second row is not.
-    assert "❯" in rendered_lines[0]
-    assert "❯" not in rendered_lines[1]
-    assert "Ctrl-O" in rendered_lines[0]
-    assert rendered_lines[0].count("/editor") == 1
+    # A blank gap line precedes the list; a blank separator and footer legend
+    # follow it, so the menu reads as its own region.
+    assert content.line_count == len(completions) + 3
+    assert rendered_lines[0].strip() == ""
+    assert content.cursor_position.y == 1
+    # First item row is highlighted, second is not.
+    assert "❯" in rendered_lines[1]
+    assert "❯" not in rendered_lines[2]
+    assert "Ctrl-O" in rendered_lines[1]
+    assert rendered_lines[1].count("/editor") == 1
+    # Blank separator then the footer legend on the last two lines.
+    assert rendered_lines[-2].strip() == ""
+    assert rendered_lines[-1].strip() == "Enter to select · ↑/↓ to navigate · Esc to cancel"
+
+
+def _slash_completions(count: int) -> list[Completion]:
+    return [
+        Completion(
+            text=f"/cmd{i}",
+            start_position=0,
+            display=f"/cmd{i}",
+            display_meta=f"command number {i}",
+        )
+        for i in range(count)
+    ]
+
+
+def test_slash_menu_footer_folds_in_overflow_count_when_list_exceeds_height(monkeypatch):
+    """When more completions exist than fit, the footer leads with the hidden
+    count alongside the navigation legend instead of silently truncating."""
+    completions = _slash_completions(20)
+    complete_state = SimpleNamespace(completions=completions, complete_index=None)
+    app = SimpleNamespace(current_buffer=SimpleNamespace(complete_state=complete_state))
+    monkeypatch.setattr(prompt_mod, "get_app_or_none", lambda: app)
+
+    control = SlashCommandMenuControl(left_padding=lambda: 0)
+    content = control.create_content(width=80, height=5)
+
+    rendered_lines = [
+        "".join(fragment[1] for fragment in content.get_line(i)) for i in range(content.line_count)
+    ]
+
+    # Gap line + visible items + blank separator + footer, within the 5-row budget.
+    assert content.line_count == 5
+    assert rendered_lines[0].strip() == ""
+    assert rendered_lines[-2].strip() == ""
+    footer = rendered_lines[-1].strip()
+    visible_items = content.line_count - 3  # minus gap, separator, footer
+    assert footer.startswith(f"+{20 - visible_items} more · ")
+    assert footer.endswith("Enter to select · ↑/↓ to navigate · Esc to cancel")
+
+
+def test_slash_menu_footer_shows_legend_without_count_when_list_fits(monkeypatch):
+    completions = _slash_completions(2)
+    complete_state = SimpleNamespace(completions=completions, complete_index=None)
+    app = SimpleNamespace(current_buffer=SimpleNamespace(complete_state=complete_state))
+    monkeypatch.setattr(prompt_mod, "get_app_or_none", lambda: app)
+
+    control = SlashCommandMenuControl(left_padding=lambda: 0)
+    content = control.create_content(width=80, height=6)
+
+    rendered_lines = [
+        "".join(fragment[1] for fragment in content.get_line(i)) for i in range(content.line_count)
+    ]
+
+    assert content.line_count == len(completions) + 3  # gap + items + separator + footer
+    assert rendered_lines[-2].strip() == ""
+    assert rendered_lines[-1].strip() == "Enter to select · ↑/↓ to navigate · Esc to cancel"
+    assert not any("more · " in line for line in rendered_lines)
+
+
+def test_annotated_plain_command_meta_has_no_tag():
+    completer = SlashCommandCompleter(
+        [_make_command("help")],
+        annotate_meta=True,
+        command_scope="command",
+    )
+
+    completions = _completions(completer, "/he")
+
+    assert completions[0].display_meta_text == "help command"
+    assert "[command]" not in completions[0].display_meta_text
 
 
 def test_find_prompt_float_container_supports_conditional_container_shape():