# Bug Report: `pmat embed` Shows Wrong Examples

**Date**: 2025-10-31
**Reporter**: User feedback
**Severity**: Low → ✅ FIXED
**Component**: CLI - embed subcommand help text
**Status**: GREEN phase complete (embed-specific examples added)

## Description

When running `pmat embed` (without subcommand), the help text shows correct usage information but includes generic PMAT examples that have nothing to do with the embed functionality.

## Steps to Reproduce

```bash
pmat embed
```

## Actual Output

```
Manage semantic search embeddings (PMAT-SEARCH-011)

Usage: pmat embed [OPTIONS] <COMMAND>

Commands:
  sync    Sync embeddings for codebase
  status  Show embedding database status
  clear   Clear all embeddings (requires --confirm)
  help    Print this message or the help of the given subcommand(s)

Options:
      --mode <MODE>                  Force specific mode (auto-detected by default) [possible values: cli, mcp]
  -v, --verbose                      Enable verbose output (info level)
  -q, --quiet                        Enable quiet mode (errors only)
      --debug                        Enable debug output (debug level)
      --trace                        Enable trace output (trace level)
      --trace-filter <TRACE_FILTER>  Custom trace filter (overrides other flags) Example: --trace-filter="paiml=debug,cache=trace" [env: RUST_LOG=]
      --color <COLOR>                Control color output [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help (see more with '--help')

EXAMPLES:
# Analyze code complexity
pmat analyze complexity --project-path .

# Find technical debt
pmat analyze satd --path .

# Find dead code
pmat analyze dead-code --path .

# Generate project context
pmat context

# Run quality gates
pmat quality-gate --strict

# Start agent daemon
pmat agent start
```

## Expected Examples

Should show examples relevant to embedding functionality:

```
EXAMPLES:
# Sync embeddings for current codebase
pmat embed sync

# Check embedding database status
pmat embed status

# Clear all embeddings (requires confirmation)
pmat embed clear --confirm

# Sync with verbose output
pmat embed sync --verbose
```

## Analysis

- Help text correctly describes the embed subcommand and its options
- EXAMPLES section shows generic PMAT examples instead of embed-specific examples
- Likely using wrong template or shared examples constant

## Impact

- Low severity - doesn't break functionality
- Confusing for users trying to learn embed command usage
- Reduces discoverability of embed features

## Files to Investigate

- `server/src/cli/mod.rs` - CLI examples definition
- Clap derive macros for embed subcommand
- Shared examples constant or template

## Fix Applied

**Root Cause**: EmbedCommands enum inherited generic examples from root CLI `after_help`

**Solution**: Added embed-specific `after_help` attribute to EmbedCommands enum

**Files Modified**:
- `server/src/cli/commands.rs:3968-3982` - Added embed-specific examples via `#[command(after_help = "...")]`
- `server/tests/bug_001_002_003_embed_tests.rs` - Tests 4, 5 verify embed-specific examples
- `bug-reports/003-embed-wrong-examples.md` - Updated to FIXED

**TDD Approach**:
1. ✅ RED: 2 tests for embed-specific examples (tests 4, 5)
2. ✅ GREEN: Added `#[command(after_help = "...")]` with 6 embed examples
3. ✅ Verification: Code compiles

**Implementation Details**:
```rust
// Before (inherited generic examples):
#[derive(Subcommand)]
pub enum EmbedCommands {

// After (embed-specific examples):
#[derive(Subcommand)]
#[command(after_help = "EXAMPLES:
# Sync embeddings for current codebase
pmat embed sync

# Check embedding database status
pmat embed status

# Clear all embeddings (requires confirmation)
pmat embed clear --confirm

# Sync with verbose output
pmat embed sync --verbose

# Check status in JSON format
pmat embed status --format json")]
pub enum EmbedCommands {
```

**Impact**: Users now see relevant embed examples when running `pmat embed --help`, improving discoverability.
