refactor: use 'usage:' instead of 'mux:' for command descriptions

- Frontmatter field changed from 'description' to 'usage'
- Executable comment changed from '# mux: ...' to '# usage: ...'
- Updated all docs examples to show usage comments
- Pattern is case-insensitive for flexibility

The 'usage:' pattern is more conventional and self-documenting.

Author: ammar-agent

docs/hooks/slash-commands.mdx

@@ -7,40 +7,70 @@ Add files to `.mux/commands/` to define custom slash commands. The file's conten
 
 ## Quick Start
 
-The simplest command is a text file:
+The simplest command is a markdown file:
 
 ```bash
 mkdir -p .mux/commands
-echo "Refactor the code to follow DRY (Don't Repeat Yourself) principles." > .mux/commands/dry.txt
+cat > .mux/commands/dry.md << 'EOF'
+---
+usage: /dry - refactor code to follow DRY principles
+---
+Refactor the code to follow DRY (Don't Repeat Yourself) principles.
+EOF
 ```
 
-Now type `/dry` in chat - the file contents become your message.
+Now type `/dry` in chat - the file contents (after frontmatter) become your message.
 
 ## File Types
 
-Commands can be either **static files** or **executable scripts**:
+Commands can be either **static markdown files** or **executable scripts**:
 
-| Type       | File                        | Behavior                            |
-| ---------- | --------------------------- | ----------------------------------- |
-| Static     | `<name>.txt` or `<name>.md` | Contents read verbatim              |
-| Executable | `<name>` (no extension)     | Script runs, stdout becomes message |
+| Type       | File                    | Behavior                                      |
+| ---------- | ----------------------- | --------------------------------------------- |
+| Static     | `<name>.md`             | Contents read verbatim (frontmatter stripped) |
+| Executable | `<name>` (no extension) | Script runs, stdout becomes message           |
 
-Static files are checked first (`.txt` before `.md`), so you can override an executable with a text file.
+Static `.md` files take precedence over executables with the same name.
 
 ## File Convention
 
-- **Location**: `<workspacePath>/.mux/commands/<name>[.txt|.md]`
+- **Location**: `<workspacePath>/.mux/commands/<name>.md` or `<name>` (executable)
 - **Name format**: lowercase letters, numbers, and hyphens (e.g., `my-command`)
 - **Executables**: must have shebang (`#!/bin/bash`, `#!/usr/bin/env node`, etc.)
 
-## Progressive Examples
+## Usage Comments
+
+Add a `usage:` line to show a description in autocomplete:
 
-### Level 1: Static File
+**Markdown files** - use YAML frontmatter:
 
-The simplest command is a text file (`.txt` or `.md`):
+```markdown
+---
+usage: /dry - refactor code to follow DRY principles
+---
 
+Your prompt content here...
 ```
-# .mux/commands/dry.txt
+
+**Executable scripts** - use a comment after the shebang:
+
+```bash
+#!/bin/bash
+# usage: /context - show current git context
+```
+
+## Progressive Examples
+
+### Level 1: Static Markdown File
+
+The simplest command is a markdown file with optional frontmatter:
+
+```markdown
+# .mux/commands/dry.md
+
+---
+
+## usage: /dry - refactor code to follow DRY principles
 
 Refactor the code to follow DRY (Don't Repeat Yourself) principles.
 Identify repeated patterns and extract them into reusable functions or modules.
@@ -55,7 +85,7 @@ For dynamic content, use an executable:
 ```bash
 #!/usr/bin/env bash
 # .mux/commands/context
-# Usage: /context
+# usage: /context - show current git context
 
 echo "Current directory: $(pwd)"
 echo "Git branch: $(git branch --show-current)"
@@ -72,7 +102,7 @@ Executable commands receive arguments from the same line:
 ```bash
 #!/usr/bin/env bash
 # .mux/commands/pr-review
-# Usage: /pr-review <PR-NUM>
+# usage: /pr-review <PR-NUM> - review a pull request
 
 pr_num="$1"
 if [ -z "$pr_num" ]; then
@@ -109,7 +139,7 @@ Use exit code 2 when a command wants to show a preview without sending:
 ```bash
 #!/usr/bin/env bash
 # .mux/commands/preview-diff
-# Shows staged changes - exit 2 to let user decide
+# usage: /preview-diff - preview staged changes without sending
 
 diff=$(git diff --cached)
 if [ -z "$diff" ]; then
@@ -146,7 +176,7 @@ Custom commands receive the same [environment variables](/hooks/environment-vari
 ````bash
 #!/usr/bin/env bash
 # .mux/commands/review
-# Usage: /review <file>
+# usage: /review <file> - review a specific file
 
 file="${1:-}"
 if [ -z "$file" ]; then
@@ -166,7 +196,7 @@ echo '```'
 ```javascript
 #!/usr/bin/env node
 // .mux/commands/deps
-// Usage: /deps - shows outdated npm dependencies
+// usage: /deps - show outdated npm dependencies
 
 const { execSync } = require("child_process");
 

src/browser/stories/App.slashCommands.stories.tsx

@@ -73,10 +73,10 @@ export const WithCustomCommands: AppStory = {
             [
               DEFAULT_WORKSPACE_ID,
               [
-                { name: "dry", description: "Do a dry run without making changes" },
-                { name: "review", description: "Review changes before committing" },
-                { name: "context", description: "Summarize project context" },
-                { name: "pr-summary", description: "Generate a PR description" },
+                { name: "dry", description: "/dry - do a dry run without making changes" },
+                { name: "review", description: "/review - review changes before committing" },
+                { name: "context", description: "/context - summarize project context" },
+                { name: "pr-summary", description: "/pr-summary - generate a PR description" },
               ],
             ],
           ]),
@@ -126,9 +126,9 @@ export const FilteredCommands: AppStory = {
             [
               DEFAULT_WORKSPACE_ID,
               [
-                { name: "dry", description: "Do a dry run" },
+                { name: "dry", description: "/dry - do a dry run" },
                 { name: "review" },
-                { name: "context", description: "Summarize project context" },
+                { name: "context", description: "/context - summarize project context" },
               ],
             ],
           ]),

src/node/services/slashCommandService.ts

@@ -20,8 +20,8 @@ const COMMAND_NAME_REGEX = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /** Static file extension (markdown only, supports frontmatter) */
 const STATIC_FILE_EXTENSION = ".md";
 
-/** Regex to match magic comment for description in executables: # mux: <description> */
-const MAGIC_COMMENT_REGEX = /^#\s*mux:\s*(.+)$/;
+/** Regex to match usage comment in executables: # usage: <usage> */
+const USAGE_COMMENT_REGEX = /^#\s*usage:\s*(.+)$/i;
 
 export interface SlashCommand {
   name: string;
@@ -162,26 +162,26 @@ export class SlashCommandService extends EventEmitter {
   }
 
   /**
-   * Parse description from markdown frontmatter.
+   * Parse usage from markdown frontmatter.
    */
   private parseMarkdownDescription(content: string): string | undefined {
     const { frontmatter } = parseSimpleFrontmatter(content);
-    return typeof frontmatter.description === "string" ? frontmatter.description : undefined;
+    return typeof frontmatter.usage === "string" ? frontmatter.usage : undefined;
   }
 
   /**
-   * Parse description from executable magic comment.
-   * Looks for `# mux: <description>` in first few lines after shebang.
+   * Parse usage from executable comment.
+   * Looks for `# usage: <usage>` in first few lines after shebang.
    */
   private parseExecutableDescription(content: string): string | undefined {
     const lines = content.split("\n");
-    // Skip shebang, check next few lines for magic comment
+    // Skip shebang, check next few lines for usage comment
     for (let i = 0; i < Math.min(lines.length, 5); i++) {
       const line = lines[i].trim();
       // Skip shebang
       if (line.startsWith("#!")) continue;
-      // Check for magic comment
-      const match = MAGIC_COMMENT_REGEX.exec(line);
+      // Check for usage comment
+      const match = USAGE_COMMENT_REGEX.exec(line);
       if (match) {
         return match[1].trim();
       }

tests/ipc/slashCommands.test.ts

@@ -288,30 +288,30 @@ describeIntegration("Custom Slash Commands (Backend)", () => {
       await createStaticCommand(
         metadata.namedWorkspacePath,
         "with-desc",
-        "---\ndescription: My cool command\n---\nBody content"
+        "---\nusage: /with-desc - my cool command\n---\nBody content"
       );
 
       const result = await env.orpc.workspace.slashCommands.list({ workspaceId });
 
       const cmd = result.commands.find((c) => c.name === "with-desc");
       expect(cmd).toBeDefined();
-      expect(cmd?.description).toBe("My cool command");
+      expect(cmd?.description).toBe("/with-desc - my cool command");
     });
   }, 30_000);
 
-  test("listSlashCommands extracts description from executable magic comment", async () => {
+  test("listSlashCommands extracts description from executable usage comment", async () => {
     await withSharedWorkspace("anthropic", async ({ env, workspaceId, metadata }) => {
       await createExecutableCommand(
         metadata.namedWorkspacePath,
-        "magic-desc",
-        '#!/bin/bash\n# mux: Run tests with coverage\necho "test"'
+        "usage-desc",
+        '#!/bin/bash\n# usage: /usage-desc - run tests with coverage\necho "test"'
       );
 
       const result = await env.orpc.workspace.slashCommands.list({ workspaceId });
 
-      const cmd = result.commands.find((c) => c.name === "magic-desc");
+      const cmd = result.commands.find((c) => c.name === "usage-desc");
       expect(cmd).toBeDefined();
-      expect(cmd?.description).toBe("Run tests with coverage");
+      expect(cmd?.description).toBe("/usage-desc - run tests with coverage");
     });
   }, 30_000);
 });