markitect-main/docs/ASSET_MANAGEMENT_USER_GUIDE.md

# Asset Management User Guide

Welcome to MarkiTect's Asset Management System - a powerful solution for managing images, files, and document packages with automatic deduplication and cross-platform compatibility.

## Quick Start

### Basic Asset Operations

```bash
# Add an asset to the registry
markitect asset add path/to/image.png

# List all managed assets
markitect asset list

# Get information about a specific asset
markitect asset info <asset-hash>

# Remove an asset from the registry
markitect asset remove <asset-hash>
```

### Document Packaging

```bash
# Create a portable .mdpkg package
markitect package create my-document/ my-document.mdpkg

# Extract a package to a workspace
markitect package extract my-document.mdpkg workspace/

# Initialize a new asset workspace
markitect workspace init my-workspace/
```

## Core Concepts

### Content-Addressable Storage

MarkiTect uses content-based addressing to store assets efficiently:

- **Automatic Deduplication**: Identical files are stored only once
- **Content Hashing**: Each asset gets a unique SHA-256 hash
- **Shared Storage**: Multiple documents can reference the same asset
- **Integrity Verification**: Content corruption is automatically detected

### Document Packages (.mdpkg)

Document packages are ZIP files containing:

- Markdown content
- All referenced assets
- Asset manifest with metadata
- Cross-references for asset resolution

Benefits:
- **Portable**: Everything needed in one file
- **Efficient**: Deduplicated assets reduce file size
- **Reliable**: Integrity verification ensures data consistency

### Workspace Management

Workspaces provide organized environments for document editing:

- **Symlink Optimization**: Assets linked (not copied) for efficiency
- **Cross-Platform**: Automatic fallback to file copying on Windows
- **Isolation**: Each workspace is independent and portable

## Detailed Usage

### Asset Management Workflow

1. **Add Assets to Registry**
   ```bash
   markitect asset add images/logo.png
   markitect asset add documents/manual.pdf
   markitect asset add screenshots/*.png
   ```

2. **Verify Asset Storage**
   ```bash
   markitect asset list
   # Shows all registered assets with hashes and metadata
   ```

3. **Get Asset Information**
   ```bash
   markitect asset info a1b2c3d4...
   # Shows file path, size, creation date, MIME type
   ```

### Document Packaging Workflow

1. **Prepare Document Directory**
   ```
   my-document/
   ├── README.md              # Main content
   ├── assets/                # Asset directory
   │   ├── logo.png
   │   ├── diagram.svg
   │   └── screenshot.jpg
   └── subdoc/
       └── detail.md
   ```

2. **Create Package**
   ```bash
   markitect package create my-document/ release/my-document.mdpkg
   ```

3. **Verify Package Contents**
   ```bash
   markitect package info release/my-document.mdpkg
   # Shows package contents, asset count, compression ratio
   ```

4. **Extract Package**
   ```bash
   markitect package extract release/my-document.mdpkg workspace/extracted/
   ```

### Workspace Operations

1. **Initialize Workspace**
   ```bash
   markitect workspace init project-workspace/
   ```

2. **Import Existing Package**
   ```bash
   markitect workspace import my-document.mdpkg project-workspace/
   ```

3. **Sync Asset Changes**
   ```bash
   markitect workspace sync project-workspace/
   # Updates asset links after registry changes
   ```

## Advanced Features

### Batch Operations

Process multiple assets efficiently:

```bash
# Add all images in a directory
markitect asset add --recursive images/

# Create packages for multiple documents
markitect package create --batch docs/ packages/

# Batch extract multiple packages
markitect package extract --batch packages/ workspace/
```

### Asset Discovery

Automatically find and register assets in documents:

```bash
# Scan document for asset references
markitect asset discover my-document/

# Auto-register discovered assets
markitect asset discover --register my-document/
```

### Performance Monitoring

Track asset operations for optimization:

```bash
# Enable performance monitoring
markitect config set asset.monitor_performance true

# View performance metrics
markitect asset stats

# Export performance data
markitect asset export-metrics metrics.json
```

## Configuration

### Global Configuration

```bash
# Set default asset storage location
markitect config set asset.storage_path /path/to/assets

# Configure deduplication strategy
markitect config set asset.deduplication_strategy content_hash

# Set package compression level
markitect config set package.compression_level 6
```

### Project-Specific Configuration

Create `.markitect.config` in your project:

```json
{
  "asset": {
    "storage_path": "./project-assets",
    "auto_discover": true,
    "include_patterns": ["*.png", "*.jpg", "*.svg", "*.pdf"],
    "exclude_patterns": ["**/temp/*", "**/cache/*"]
  },
  "package": {
    "compression_level": 9,
    "include_metadata": true,
    "verify_integrity": true
  }
}
```

## Best Practices

### Asset Organization

1. **Use Descriptive Filenames**: Clear names help with asset management
2. **Organize by Type**: Group similar assets (images/, docs/, etc.)
3. **Avoid Duplicates**: Let the system handle deduplication automatically
4. **Regular Cleanup**: Remove unused assets periodically

### Package Management

1. **Version Your Packages**: Use semantic versioning for package names
2. **Document Dependencies**: Include README files explaining asset usage
3. **Test Extraction**: Always verify packages extract correctly
4. **Backup Originals**: Keep source documents separate from packages

### Workspace Hygiene

1. **Use Workspaces**: Don't edit packages directly
2. **Sync Regularly**: Keep workspaces updated with asset changes
3. **Clean Temporary Files**: Remove build artifacts before packaging
4. **Validate Before Packaging**: Ensure all assets are registered

## Troubleshooting

### Common Issues

**Problem**: Asset not found after adding
```bash
# Solution: Verify asset was registered
markitect asset list | grep filename
markitect asset info <hash>
```

**Problem**: Package extraction fails
```bash
# Solution: Verify package integrity
markitect package verify my-document.mdpkg
markitect package extract --force my-document.mdpkg workspace/
```

**Problem**: Symlinks not working on Windows
```bash
# Solution: Enable file copying fallback
markitect config set asset.windows_use_copy true
```

**Problem**: Large package sizes
```bash
# Solution: Check for duplicate assets
markitect asset deduplicate
markitect package optimize my-document.mdpkg
```

### Performance Issues

**Slow Asset Operations**:
- Check disk space and permissions
- Verify storage path is accessible
- Consider SSD for asset storage

**Large Memory Usage**:
- Reduce batch operation size
- Enable asset caching
- Check for memory leaks with monitoring

### Error Recovery

**Corrupted Registry**:
```bash
# Rebuild registry from stored assets
markitect asset rebuild-registry

# Verify registry integrity
markitect asset verify-registry
```

**Missing Assets**:
```bash
# Find orphaned references
markitect asset find-orphans

# Clean up broken references
markitect asset cleanup --orphans
```

## API Reference

For developers integrating with the asset management system:

```python
from markitect.assets import AssetManager

# Initialize asset manager
manager = AssetManager(storage_path="./assets")

# Add asset
result = manager.add_asset("path/to/file.png")
asset_hash = result['content_hash']

# Get asset info
info = manager.get_asset_info(asset_hash)

# Create package
manager.create_package("document/", "output.mdpkg")

# Extract package
manager.extract_package("input.mdpkg", "workspace/")
```

## Support

For additional help:

- Check the [FAQ](FAQ.md) for common questions
- Browse [examples](../examples/) for usage patterns
- Report issues on the project repository
- Join the community discussion forums

## Release Notes

**Version 1.0.0** (Asset Management Milestone)
- Complete asset management implementation
- Cross-platform compatibility
- Production-ready performance
- Comprehensive CLI integration
- Full documentation and examples