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

# 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

# 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

   markitect asset add images/logo.png
   markitect asset add documents/manual.pdf
   markitect asset add screenshots/*.png
   

2. Verify Asset Storage

   markitect asset list
   # Shows all registered assets with hashes and metadata
   

3. Get Asset Information

   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

   markitect package create my-document/ release/my-document.mdpkg
   

3. Verify Package Contents

   markitect package info release/my-document.mdpkg
   # Shows package contents, asset count, compression ratio
   

4. Extract Package

   markitect package extract release/my-document.mdpkg workspace/extracted/
   

Workspace Operations

1. Initialize Workspace

   markitect workspace init project-workspace/
   

2. Import Existing Package

   markitect workspace import my-document.mdpkg project-workspace/
   

3. Sync Asset Changes

   markitect workspace sync project-workspace/
   # Updates asset links after registry changes
   

Advanced Features

Batch Operations

Process multiple assets efficiently:

# 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:

# 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:

# 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

# 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:

{
  "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

# Solution: Verify asset was registered
markitect asset list | grep filename
markitect asset info <hash>

Problem: Package extraction fails

# Solution: Verify package integrity
markitect package verify my-document.mdpkg
markitect package extract --force my-document.mdpkg workspace/

Problem: Symlinks not working on Windows

# Solution: Enable file copying fallback
markitect config set asset.windows_use_copy true

Problem: Large package sizes

# 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:

# Rebuild registry from stored assets
markitect asset rebuild-registry

# Verify registry integrity
markitect asset verify-registry

Missing Assets:

# 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:

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 for common questions
• Browse 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