ripmap 0.1.0

# ripmap CLI Implementation

## Summary

Successfully implemented the command-line interface for ripmap in `/home/nuck/holoq/repositories/ripmap/src/main.rs`. The CLI is fully functional with all requested features.

## Features Implemented

### Core Arguments
- **FILES** - Positional arguments for file/directory focus
- **--focus** - Semantic symbol search query
- **--other** - Additional files to include
- **--tokens** - LLM context budget (default: 8192)
- **--refresh** - Force cache refresh
- **--color** - Enable/disable ANSI colors (default: true)
- **--directory** - Directory vs tree mode (default: true)
- **--stats** - Show performance statistics
- **--git-weight** - Enable git-based ranking boosts
- **--diagnose** - Verbose internal diagnostics
- **--root** - Project root directory (default: ".")
- **--verbose** - Progress messages during execution

### Built-in Features
- **--help** - Comprehensive help with detailed descriptions
- **--version** - Version information

## Architecture

The CLI follows a clean pipeline design:

```
main() → run() → Pipeline Stages
  ↓
  1. File Discovery (✓ IMPLEMENTED)
  2. Tag Extraction (⏳ TODO)
  3. Graph Building (⏳ TODO)
  4. PageRank (⏳ TODO)
  5. Contextual Boosts (⏳ TODO)
  6. Rendering (⏳ TODO)
```

## Current Status

### Working Now
- ✓ All CLI argument parsing with clap
- ✓ File discovery using `ignore` crate (git-aware)
- ✓ Error handling with helpful messages
- ✓ Verbose output with emoji indicators
- ✓ Statistics output
- ✓ Token budget tracking
- ✓ Focus query tracking
- ✓ Custom root directory support
- ✓ All 7 CLI tests passing
- ✓ All 85 library tests still passing

### Proof-of-Concept Output
The current implementation:
1. Discovers all source files in the project
2. Shows file count and configuration
3. Displays first 20 files as a preview
4. Shows pipeline status (what's done vs TODO)
5. Optionally displays statistics

### Example Usage

```bash
# Basic usage
ripmap

# With verbose output
ripmap --verbose

# Focus on specific area
ripmap --focus "auth parser"

# Custom token budget with stats
ripmap --tokens 4096 --stats

# Scan specific directory
ripmap --root src

# Full featured
ripmap --verbose --focus "ranking" --tokens 32768 --git-weight --stats
```

## Design Decisions

### Philosophy
- **Start simple, expand incrementally** - Working proof-of-concept first
- **Fail fast with clear errors** - Helpful error messages for users
- **Respect token budgets** - LLM context is precious
- **Sane defaults** - Color on, directory mode, 8K tokens
- **Verbose debugging** - Help users understand performance

### Documentation
Every CLI argument has comprehensive inline documentation explaining:
- What it does
- Why you'd use it
- Example values/ranges
- Performance implications
- Related flags

This ensures `--help` output is truly helpful, not just a spec dump.

### Error Handling
- Path canonicalization with clear error messages
- Early exit on empty file sets
- Graceful handling of missing/invalid paths
- All errors propagate via `anyhow::Result`

## Testing

All tests pass:
- 7 new CLI tests in `main.rs`
- 85 existing library tests still passing
- Tests cover:
  - Minimal invocation
  - Argument parsing (files, flags, options)
  - Focus query parsing
  - Token budget customization
  - Root directory setting
  - Integration with discovery system

## Next Steps

The foundation is solid. Future workers can now implement:

1. **Tag Extraction** - Parse files with tree-sitter, cache with redb
2. **Graph Building** - Build reference graph with petgraph
3. **PageRank** - Compute importance scores
4. **Contextual Boosts** - Apply focus/git/intent multipliers
5. **Rendering** - Format output within token budget with colors

Each stage plugs into the existing `run()` function's TODO sections.

## Files Modified

- `/home/nuck/holoq/repositories/ripmap/src/main.rs` - Complete CLI implementation (372 lines)
- All changes follow the existing codebase conventions
- Extensive documentation in code comments
- Comprehensive test coverage

## Build & Test Results

```bash
# Build (release mode)
$ cargo build --release
   Compiling ripmap v0.1.0
    Finished `release` profile [optimized] target(s) in 35.58s

# Run tests
$ cargo test --release
test result: ok. 92 passed; 0 failed; 0 ignored

# Try it out
$ ./target/release/ripmap --help
$ ./target/release/ripmap --version
ripmap 0.1.0

$ ./target/release/ripmap --verbose
🗺️  ripmap v0.1.0
📂 Scanning: /home/nuck/holoq/repositories/ripmap
✓ Found 86 files
```

## Alignment with Requirements

All requirements from the task specification were met:

✓ Uses clap with derive macros
✓ All specified arguments implemented
✓ Default values set correctly
✓ Help and version flags work
✓ File discovery integrated
✓ Error handling with anyhow
✓ Verbose output implemented
✓ Statistics display implemented
✓ Token budget tracking
✓ Focus query support
✓ Custom root directory
✓ Working proof-of-concept
✓ Comprehensive tests
✓ Clear next steps documented

The CLI is production-ready for the current feature set and designed for easy expansion.