fix: CLI consistency — short aliases, default displays, help text

docs/src/content/docs/reference/cli-commands.md

@@ -91,7 +91,7 @@ apm install [PACKAGES...] [OPTIONS]
 - `--force` - Overwrite locally-authored files on collision; bypass security scan blocks
 - `--dry-run` - Show what would be installed without installing
 - `--parallel-downloads INTEGER` - Max concurrent package downloads (default: 4, 0 to disable)
-- `--verbose` - Show individual file paths and full error details in the diagnostic summary
+- `-v, --verbose` - Show individual file paths and full error details in the diagnostic summary
 - `--trust-transitive-mcp` - Trust self-defined MCP servers from transitive packages (skip re-declaration requirement)
 - `--dev` - Add packages to [`devDependencies`](../manifest-schema/#5-devdependencies) instead of `dependencies`. Dev deps are installed locally but excluded from `apm pack --format plugin` bundles
 
@@ -342,7 +342,7 @@ apm prune --dry-run
 
 ### `apm audit` - Scan for hidden Unicode characters
 
-Scan installed packages or arbitrary files for hidden Unicode characters that could embed invisible instructions in prompt files.
+Scan installed packages or any file for hidden Unicode characters that could embed invisible instructions in prompt files.
 
 ```bash
 apm audit [PACKAGE] [OPTIONS]
@@ -716,15 +716,15 @@ apm mcp list [OPTIONS]
 ```
 
 **Options:**
-- `--limit INTEGER` - Number of results to show
+- `--limit INTEGER` - Number of results to show (default: 20)
 
 **Examples:**
 ```bash
 # List available MCP servers
 apm mcp list
 
 # Limit results
-apm mcp list --limit 20
+apm mcp list --limit 50
 ```
 
 #### `apm mcp search` - Search MCP servers
@@ -868,7 +868,7 @@ apm compile [OPTIONS]
 ```
 
 **Options:**
-- `-o, --output TEXT` - Output file path (for single-file mode)
+- `-o, --output TEXT` - Output file path (use with `--single-agents` legacy mode)
 - `-t, --target [vscode|agents|claude|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
 - `--chatmode TEXT` - Chatmode to prepend to the AGENTS.md file
 - `--dry-run` - Preview compilation without writing files (shows placement decisions)
@@ -1044,7 +1044,7 @@ apm config
 apm config
 ```
 
-#### `apm config get` - Get a configuration value
+#### `apm config get` - Get one or all configuration values
 
 Get a specific configuration value or display all configuration values.
 
@@ -1187,7 +1187,7 @@ apm runtime remove [OPTIONS] {copilot|codex|llm}
 - `{copilot|codex|llm}` - Runtime to remove
 
 **Options:**
-- `--yes` - Confirm the action without prompting
+- `-y, --yes` - Confirm the action without prompting
 
 #### `apm runtime status` - Show runtime status
 

src/apm_cli/commands/audit.py

@@ -379,7 +379,7 @@ def _preview_strip(
 # ── Command ────────────────────────────────────────────────────────
 
 
-@click.command(help="Scan installed packages for hidden Unicode characters")
+@click.command(help="Scan installed packages (or any file) for hidden Unicode characters")
 @click.argument("package", required=False)
 @click.option(
     "--file",

src/apm_cli/commands/compile/cli.py

@@ -170,7 +170,7 @@ def _get_validation_suggestion(error_msg):
     "--output",
     "-o",
     default=AGENTS_MD_FILENAME,
-    help="Output file path (for single-file mode)",
+    help="Output file path (use with --single-agents legacy mode)",
 )
 @click.option(
     "--target",

src/apm_cli/commands/config.py

@@ -136,7 +136,7 @@ def set(key, value):
         sys.exit(1)
 
 
-@config.command(help="Get a configuration value")
+@config.command(help="Get one or all configuration values")
 @click.argument("key", required=False)
 def get(key):
     """Get a configuration value or show all configuration.

src/apm_cli/commands/install.py

@@ -321,7 +321,7 @@ def _validate_package_exists(package):
     "--dry-run", is_flag=True, help="Show what would be installed without installing"
 )
 @click.option("--force", is_flag=True, help="Overwrite locally-authored files on collision and deploy despite critical security findings")
-@click.option("--verbose", is_flag=True, help="Show detailed installation information")
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed installation information")
 @click.option(
     "--trust-transitive-mcp",
     is_flag=True,

src/apm_cli/commands/mcp.py

@@ -288,7 +288,7 @@ def show(ctx, server_name):
 
 
 @mcp.command(help="List all available MCP servers")
-@click.option("--limit", default=20, help="Number of results to show")
+@click.option("--limit", default=20, show_default=True, help="Number of results to show")
 @click.pass_context
 def list(ctx, limit):
     """List all available MCP servers in the registry."""

src/apm_cli/commands/pack.py

@@ -16,6 +16,7 @@
     "fmt",
     type=click.Choice(["apm", "plugin"]),
     default="apm",
+    show_default=True,
     help="Bundle format.",
 )
 @click.option(

src/apm_cli/commands/runtime.py

@@ -124,7 +124,7 @@ def list():
 
 @runtime.command(help="Remove an installed runtime")
 @click.argument("runtime_name", type=click.Choice(["copilot", "codex", "llm"]))
-@click.confirmation_option(prompt="Are you sure you want to remove this runtime?", help="Confirm the action without prompting")
+@click.confirmation_option("-y", "--yes", prompt="Are you sure you want to remove this runtime?", help="Confirm the action without prompting")
 def remove(runtime_name):
     """Remove an installed runtime from APM management."""
     try: