fix: CLI consistency — align help text with docs

docs/cli-reference.md

@@ -264,11 +264,11 @@ This makes all package prompts available in VSCode, Claude Code, and compatible
 Remove installed APM packages and their integrated files.
 
 ```bash
-apm uninstall PACKAGE [OPTIONS]
+apm uninstall [OPTIONS] PACKAGES...
 ```
 
 **Arguments:**
-- `PACKAGE` - Package to uninstall. Accepts any format — shorthand (`owner/repo`), HTTPS URL, SSH URL, or FQDN. APM resolves it to the canonical identity stored in `apm.yml`.
+- `PACKAGES...` - One or more packages to uninstall. Accepts any format — shorthand (`owner/repo`), HTTPS URL, SSH URL, or FQDN. APM resolves each to the canonical identity stored in `apm.yml`.
 
 **Options:**
 - `--dry-run` - Show what would be removed without removing
@@ -672,23 +672,23 @@ Available scripts:
   debug: RUST_LOG=debug codex hello-world.prompt.md
 ```
 
-### `apm compile` - 📝 Compile APM context files into AGENTS.md
+### `apm compile` - 📝 Compile APM context into distributed AGENTS.md files
 
-Compile APM context files (chatmodes, instructions, contexts) into a single intelligent AGENTS.md file with conditional sections, markdown link resolution, and project setup auto-detection.
+Compile APM context files (chatmodes, instructions, contexts) into distributed AGENTS.md files with conditional sections, markdown link resolution, and project setup auto-detection.
 
 ```bash
 apm compile [OPTIONS]
 ```
 
 **Options:**
-- `-o, --output TEXT` - Output file path (default: AGENTS.md)
+- `-o, --output TEXT` - Output file path (for single-file mode)
 - `-t, --target [vscode|agents|claude|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` - Generate content without writing file
+- `--dry-run` - Preview compilation without writing files (shows placement decisions)
 - `--no-links` - Skip markdown link resolution
 - `--with-constitution/--no-constitution` - Include Spec Kit `memory/constitution.md` verbatim at top inside a delimited block (default: `--with-constitution`). When disabled, any existing block is preserved but not regenerated.
 - `--watch` - Auto-regenerate on changes (file system monitoring)
-- `--validate` - Validate context without compiling
+- `--validate` - Validate primitives without compiling
 - `--single-agents` - Force single-file compilation (legacy mode)
 - `-v, --verbose` - Show detailed source attribution and optimizer analysis
 - `--local-only` - Ignore dependencies, compile only local primitives

src/apm_cli/cli.py

@@ -313,7 +313,7 @@ def cli(ctx):
 @cli.command(help="🚀 Initialize a new APM project")
 @click.argument("project_name", required=False)
 @click.option(
-    "--yes", "-y", is_flag=True, help="Skip prompts and use auto-detected defaults"
+    "--yes", "-y", is_flag=True, help="Skip interactive prompts and use auto-detected defaults"
 )
 @click.pass_context
 def init(ctx, project_name, yes):
@@ -4241,7 +4241,7 @@ def config(ctx):
             click.echo(f"  APM CLI Version: {get_version()}")
 
 
-@config.command(help="Set configuration value")
+@config.command(help="Set a configuration value")
 @click.argument("key")
 @click.argument("value")
 def set(key, value):
@@ -4272,7 +4272,7 @@ def set(key, value):
         sys.exit(1)
 
 
-@config.command(help="Get configuration value")
+@config.command(help="Get a configuration value")
 @click.argument("key", required=False)
 def get(key):
     """Get a configuration value or show all configuration.
@@ -4306,7 +4306,7 @@ def get(key):
                 click.echo(f"  {k}: {v}")
 
 
-@cli.group(help="Manage Coding Agent CLI runtimes")
+@cli.group(help="Manage AI runtimes")
 def runtime():
     """Manage Coding Agent CLI runtime installations and configurations."""
     pass
@@ -4330,7 +4330,7 @@ def _atomic_write(path: Path, data: str) -> None:
         raise
 
 
-@cli.group(help="Manage MCP servers")
+@cli.group(help="Browse MCP server registry")
 def mcp():
     """Manage MCP server discovery and information."""
     pass