Unify REPL help command metadata (#59)

docs/users-guide.md

@@ -3,6 +3,41 @@
 This guide captures operator-visible behaviour for the current Axinite
 runtime.
 
+## REPL commands
+
+The interactive REPL accepts slash-commands for local conversation control,
+configuration, diagnostics, jobs, and conversation threads.
+
+| Command | Description |
+| --- | --- |
+| `/help` | Show the REPL help. |
+| `/quit` | Exit the REPL. |
+| `/exit` | Exit the REPL. |
+| `/debug` | Toggle verbose output. |
+| `/undo` | Undo the last turn. |
+| `/redo` | Redo an undone turn. |
+| `/clear` | Clear the conversation. |
+| `/compact` | Compact the context window. |
+| `/new` | Start a new conversation thread. |
+| `/interrupt` | Stop the current operation. |
+| `/model` | Show or change the model. |
+| `/version` | Show version information. |
+| `/tools` | List available tools. |
+| `/ping` | Test the connection. |
+| `/status` | Show system status. |
+| `/heartbeat` | Send a heartbeat. |
+| `/job` | Manage background jobs. |
+| `/cancel` | Cancel the current operation. |
+| `/list` | List conversations. |
+| `/summarize` | Summarise a conversation. |
+| `/suggest` | Get suggestions. |
+| `/thread` | Manage conversation threads. |
+| `/resume` | Resume a conversation. |
+
+Pressing `Esc` stops the current operation. When a tool requests approval,
+respond with `yes` or `y` to approve the run, `no` or `n` to deny it, or
+`always` or `a` to approve matching requests for the session.
+
 ## Skill bundle installs
 
 Axinite now validates passive multi-file skill bundles when a skill is

src/channels/repl/formatting.rs

@@ -8,6 +8,15 @@ use unicode_width::UnicodeWidthStr;
 use super::common::sanitize_for_terminal;
 use super::input::SLASH_COMMANDS;
 
+const HELP_COMMAND_GROUPS: &[&str] = &[
+    "Commands",
+    "Conversation",
+    "Configuration",
+    "Diagnostics",
+    "Jobs",
+    "Threads",
+];
+
 /// A pending tool-use request awaiting user approval.
 pub(super) struct ToolApprovalRequest<'a> {
     pub request_id: &'a str,
@@ -38,28 +47,17 @@ pub(super) fn print_help() {
     let d = "\x1b[90m"; // dim gray (descriptions)
     let r = "\x1b[0m"; // reset
 
-    // Group commands by category
-    let general_cmds = &["/help", "/debug", "/quit", "/exit"];
-    let conversation_cmds = &["/undo", "/redo", "/clear", "/compact", "/new", "/interrupt"];
-
     println!();
     println!("  {h}IronClaw REPL{r}");
-    println!();
-    println!("  {h}Commands{r}");
-    for cmd in SLASH_COMMANDS
-        .iter()
-        .filter(|c| general_cmds.contains(&c.name))
-    {
-        println!("  {c}{:<16}{r}  {d}{}{r}", cmd.name, cmd.description);
-    }
-    println!();
-    println!("  {h}Conversation{r}");
-    for cmd in SLASH_COMMANDS
-        .iter()
-        .filter(|c| conversation_cmds.contains(&c.name))
-    {
-        println!("  {c}{:<16}{r}  {d}{}{r}", cmd.name, cmd.description);
+
+    for group in HELP_COMMAND_GROUPS {
+        println!();
+        println!("  {h}{group}{r}");
+        for cmd in SLASH_COMMANDS.iter().filter(|cmd| cmd.group == *group) {
+            println!("  {c}{:<16}{r}  {d}{}{r}", cmd.name, cmd.description);
+        }
     }
+
     println!("  {c}esc{r}              {d}stop current operation{r}");
     println!();
     println!("  {h}Approval responses{r}");

src/channels/repl/input.rs

@@ -12,106 +12,130 @@ use rustyline::{
     Cmd as ReadlineCmd, ConditionalEventHandler, Event, EventContext, Helper, RepeatCount,
 };
 
-/// Slash command entry with name and description.
+/// Slash command entry with name, description, and help grouping metadata.
 #[derive(Clone, Copy)]
 pub(super) struct SlashCommand {
     pub(super) name: &'static str,
     pub(super) description: &'static str,
+    pub(super) group: &'static str,
 }
 
 /// Slash commands available in the REPL.
 pub(super) const SLASH_COMMANDS: &[SlashCommand] = &[
     SlashCommand {
         name: "/help",
         description: "show this help",
+        group: "Commands",
     },
     SlashCommand {
         name: "/quit",
         description: "exit the repl",
+        group: "Commands",
     },
     SlashCommand {
         name: "/exit",
         description: "exit the repl",
+        group: "Commands",
     },
     SlashCommand {
         name: "/debug",
         description: "toggle verbose output",
+        group: "Commands",
     },
     SlashCommand {
         name: "/model",
         description: "show or change model",
+        group: "Configuration",
     },
     SlashCommand {
         name: "/undo",
         description: "undo the last turn",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/redo",
         description: "redo an undone turn",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/clear",
         description: "clear conversation",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/compact",
         description: "compact context window",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/new",
         description: "new conversation thread",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/interrupt",
         description: "stop current operation",
+        group: "Conversation",
     },
     SlashCommand {
         name: "/version",
         description: "show version information",
+        group: "Configuration",
     },
     SlashCommand {
         name: "/tools",
         description: "list available tools",
+        group: "Configuration",
     },
     SlashCommand {
         name: "/ping",
         description: "test connection",
+        group: "Diagnostics",
     },
     SlashCommand {
         name: "/job",
         description: "manage background jobs",
+        group: "Jobs",
     },
     SlashCommand {
         name: "/status",
         description: "show system status",
+        group: "Diagnostics",
     },
     SlashCommand {
         name: "/cancel",
         description: "cancel current operation",
+        group: "Jobs",
     },
     SlashCommand {
         name: "/list",
         description: "list conversations",
+        group: "Threads",
     },
     SlashCommand {
         name: "/heartbeat",
         description: "send heartbeat",
+        group: "Diagnostics",
     },
     SlashCommand {
         name: "/summarize",
         description: "summarize conversation",
+        group: "Threads",
     },
     SlashCommand {
         name: "/suggest",
         description: "get suggestions",
+        group: "Threads",
     },
     SlashCommand {
         name: "/thread",
         description: "manage conversation threads",
+        group: "Threads",
     },
     SlashCommand {
         name: "/resume",
         description: "resume a conversation",
+        group: "Threads",
     },
 ];