# MarkiTect Command Migration Guide

## Overview

As of this release, MarkiTect has migrated the core markdown commands (`ingest`, `get`, `list`) to use prefixed names for consistency with the existing command structure. The new commands use the `md-` prefix.

## Command Changes

| Old Command | New Command | Status |
|------------|-------------|---------|
| `markitect ingest` | `markitect md-ingest` | ✅ Active |
| `markitect get` | `markitect md-get` | ✅ Active |
| `markitect list` | `markitect md-list` | ✅ Active |

## Migration Timeline

- **Immediate**: New `md-` prefixed commands are available
- **Migration Period**: 1 month grace period for users to update their workflows
- **Deprecated**: Old unprefixed commands have been removed

## Backward Compatibility

### Bash Aliases

To ease the transition, we provide bash aliases that maintain the old command patterns:

```bash
# Source the aliases file
source aliases.sh

# Or add to your ~/.bashrc
echo "source $(pwd)/aliases.sh" >> ~/.bashrc
```

Available aliases:
- `markitect-ingest` → `markitect md-ingest`
- `markitect-get` → `markitect md-get`
- `markitect-list` → `markitect md-list`

### Convenience Aliases

Additional convenience aliases for common usage patterns:
- `md-ingest-verbose` → `markitect md-ingest --verbose`
- `md-get-output` → `markitect md-get --output`
- `md-list-json` → `markitect md-list --format json`
- `md-list-yaml` → `markitect md-list --format yaml`
- `md-list-table` → `markitect md-list --format table`
- `md-list-names` → `markitect md-list --names-only`

### Convenience Functions

The aliases file also includes useful functions:
- `md-process-dir <directory>` - Process all .md files in a directory
- `md-export-all [output-dir]` - Export all stored files to a directory
- `md-aliases` - Show available aliases and functions

## Architecture Benefits

This migration brings several benefits:

1. **Consistency**: All commands now follow the same prefix pattern
2. **Plugin Architecture**: Markdown commands are now implemented as a plugin
3. **Modularity**: Clear separation of markdown functionality
4. **Extensibility**: Easy to add new markdown variants or processors
5. **Maintainability**: Better code organization and lazy loading

## Implementation Details

### Plugin Structure

The new commands are implemented in `/markitect/plugins/builtin/markdown_commands.py` as a CommandPlugin:

```python
@register_plugin("markdown_commands")
class MarkdownCommandsPlugin(CommandPlugin):
    def get_commands(self) -> Dict[str, Any]:
        return {
            'md-ingest': self.md_ingest,
            'md-get': self.md_get,
            'md-list': self.md_list
        }
```

### CLI Integration

The plugin is automatically loaded and registered in the CLI:

```python
# Register markdown commands plugin
try:
    from .plugins.builtin.markdown_commands import MarkdownCommandsPlugin
    plugin_instance = MarkdownCommandsPlugin()
    plugin_instance.initialize()
    for command_name, command_func in plugin_instance.get_commands().items():
        cli.add_command(command_func, name=command_name)
except ImportError:
    pass  # Plugin not available
```

## Migration Checklist

- [ ] Update scripts to use `md-` prefixed commands
- [ ] Source `aliases.sh` for temporary compatibility
- [ ] Test workflows with new commands
- [ ] Update documentation and examples
- [ ] Remove dependency on old command names

## Support

If you encounter issues during migration:

1. Check that you're using the latest version
2. Source the `aliases.sh` file for temporary compatibility
3. Report issues at the project repository
4. Consult this migration guide

The new plugin architecture provides a solid foundation for future enhancements while maintaining the core functionality users depend on.