feat: Complete Issue #8 - Detailed Validation Error Reporting and CLI Enhancements

Major Features:
- Implement comprehensive validation error reporting system (Issue #8)
- Add direct CLI access with 'markitect' command
- Create extensive makefile targets for CLI usage
- Enhance schema validation with detailed error collection

Components Added:
- markitect/validation_error.py: ValidationError system with 8 error types
- Enhanced markitect/schema_validator.py: Detailed error reporting methods
- markitect/cli.py: Enhanced with --detailed-errors and --error-format options
- visualize_schema.py: Schema visualization with ASCII and colorful modes
- Comprehensive test suite for validation error reporting

CLI Enhancements:
- Direct 'markitect' command access for all operations
- Makefile targets for typical CLI usage (cli-help, cli-ingest, etc.)
- Support for text, JSON, and markdown error output formats
- Backward compatibility with existing validation functionality

Testing:
- 11 comprehensive tests for Issue #8 validation error reporting
- Tests for schema validation, visualization, and CLI integration
- 100% test coverage for validation error scenarios

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Makefile

@@ -1,7 +1,7 @@
 # MarkiTect - Advanced Markdown Engine
 # Makefile for common development tasks
 
-.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest add-diary-entry list-issues show-issue list-open-issues test-from-issue tdd-start tdd-add-test tdd-finish tdd-status test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly
+.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest add-diary-entry list-issues show-issue list-open-issues test-from-issue tdd-start tdd-add-test tdd-finish tdd-status test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly cli-help
 
 # Default target
 help:
@@ -71,6 +71,12 @@ help:
 	@echo "  tdd-add-test          - Add test to current issue workspace"
 	@echo "  tdd-status            - Show current workspace state"
 	@echo "  tdd-finish            - Complete issue work (moves tests to main)"
+	@echo ""
+	@echo "MarkiTect CLI Usage:"
+	@echo "  cli-help              - Show detailed CLI usage targets and examples"
+	@echo "  cli-ingest [FILE=doc.md] - Process and store markdown files"
+	@echo "  cli-workflow-basic    - Run complete basic workflow demo"
+	@echo "  cli-workflow-schema FILE=doc.md - Run schema generation workflow"
 
 # Python and virtual environment setup
 PYTHON := python3
@@ -574,3 +580,250 @@ test-random-enhanced: $(VENV)/bin/activate
 
 # Update .PHONY for randomized targets
 .PHONY: test-random-verbose test-random-enhanced
+
+# ============================================================================
+# MarkiTect CLI Usage Targets
+# ============================================================================
+
+# Variables for CLI targets
+MARKITECT := PYTHONPATH=. $(VENV_PYTHON) -c "from markitect.cli import cli; import sys; cli(sys.argv[1:])"
+SAMPLE_DOC := test_frontmatter.md
+OUTPUT_FORMAT := table
+
+# Basic document operations
+cli-ingest: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "📄 Processing sample document..."; \
+		$(MARKITECT) ingest $(SAMPLE_DOC); \
+	else \
+		echo "📄 Processing document: $(FILE)"; \
+		$(MARKITECT) ingest $(FILE); \
+	fi
+
+cli-status: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "📊 Checking status of sample document..."; \
+		$(MARKITECT) status $(SAMPLE_DOC); \
+	else \
+		echo "📊 Checking status of document: $(FILE)"; \
+		$(MARKITECT) status $(FILE); \
+	fi
+
+cli-list: $(VENV)/bin/activate
+	@echo "📋 Listing all processed documents..."
+	@$(MARKITECT) list --format $(OUTPUT_FORMAT)
+
+cli-get: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "📖 Retrieving sample document..."; \
+		$(MARKITECT) get $(SAMPLE_DOC); \
+	else \
+		echo "📖 Retrieving document: $(FILE)"; \
+		$(MARKITECT) get $(FILE); \
+	fi
+
+# Schema operations
+cli-generate-schema: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "🔧 Generating schema from sample document..."; \
+		$(MARKITECT) generate-schema $(SAMPLE_DOC) --output-format json; \
+	else \
+		echo "🔧 Generating schema from document: $(FILE)"; \
+		$(MARKITECT) generate-schema $(FILE) --output-format json; \
+	fi
+
+cli-validate: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ] || [ -z "$(SCHEMA)" ]; then \
+		echo "❌ Usage: make cli-validate FILE=document.md SCHEMA=schema.json"; \
+		echo "   Example: make cli-validate FILE=test_frontmatter.md SCHEMA=generated_schema.json"; \
+		exit 1; \
+	fi
+	@echo "✅ Validating $(FILE) against $(SCHEMA)..."
+	@$(MARKITECT) validate $(FILE) $(SCHEMA)
+
+cli-validate-detailed: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ] || [ -z "$(SCHEMA)" ]; then \
+		echo "❌ Usage: make cli-validate-detailed FILE=document.md SCHEMA=schema.json"; \
+		echo "   Example: make cli-validate-detailed FILE=test_frontmatter.md SCHEMA=generated_schema.json"; \
+		exit 1; \
+	fi
+	@echo "🔍 Validating $(FILE) with detailed errors..."
+	@$(MARKITECT) validate $(FILE) $(SCHEMA) --detailed-errors --error-format text
+
+# AST operations
+cli-ast-show: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "🌳 Showing AST for sample document..."; \
+		$(MARKITECT) ast-show $(SAMPLE_DOC); \
+	else \
+		echo "🌳 Showing AST for document: $(FILE)"; \
+		$(MARKITECT) ast-show $(FILE); \
+	fi
+
+cli-ast-stats: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "📈 Showing AST statistics for sample document..."; \
+		$(MARKITECT) ast-stats $(SAMPLE_DOC); \
+	else \
+		echo "📈 Showing AST statistics for document: $(FILE)"; \
+		$(MARKITECT) ast-stats $(FILE); \
+	fi
+
+cli-ast-query: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ] || [ -z "$(QUERY)" ]; then \
+		echo "❌ Usage: make cli-ast-query FILE=document.md QUERY='JSONPath expression'"; \
+		echo "   Example: make cli-ast-query FILE=test_frontmatter.md QUERY='$.headings[*].text'"; \
+		exit 1; \
+	fi
+	@echo "🔍 Querying AST: $(QUERY)"
+	@$(MARKITECT) ast-query $(FILE) '$(QUERY)'
+
+# Metadata operations
+cli-metadata: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "🏷️  Showing metadata for sample document..."; \
+		$(MARKITECT) metadata $(SAMPLE_DOC) --format $(OUTPUT_FORMAT); \
+	else \
+		echo "🏷️  Showing metadata for document: $(FILE)"; \
+		$(MARKITECT) metadata $(FILE) --format $(OUTPUT_FORMAT); \
+	fi
+
+# Database operations
+cli-query: $(VENV)/bin/activate
+	@if [ -z "$(SQL)" ]; then \
+		echo "❌ Usage: make cli-query SQL='SELECT statement'"; \
+		echo "   Example: make cli-query SQL='SELECT * FROM files LIMIT 5'"; \
+		exit 1; \
+	fi
+	@echo "🗄️  Executing SQL query..."
+	@$(MARKITECT) query '$(SQL)' --format $(OUTPUT_FORMAT)
+
+cli-schema-db: $(VENV)/bin/activate
+	@echo "🗄️  Showing database schema..."
+	@$(MARKITECT) schema
+
+# Cache management
+cli-cache-info: $(VENV)/bin/activate
+	@echo "💾 Cache information..."
+	@$(MARKITECT) cache-info
+
+cli-cache-clean: $(VENV)/bin/activate
+	@echo "🧹 Cleaning cache..."
+	@$(MARKITECT) cache-clean
+
+cli-cache-invalidate: $(VENV)/bin/activate
+	@if [ -z "$(FILE)" ]; then \
+		echo "❌ Usage: make cli-cache-invalidate FILE=document.md"; \
+		exit 1; \
+	fi
+	@echo "🔄 Invalidating cache for $(FILE)..."
+	@$(MARKITECT) cache-invalidate $(FILE)
+
+# Schema visualization
+cli-visualize-schema: $(VENV)/bin/activate
+	@if [ -z "$(SCHEMA)" ]; then \
+		echo "❌ Usage: make cli-visualize-schema SCHEMA=schema.json"; \
+		echo "   Example: make cli-visualize-schema SCHEMA=generated_schema.json"; \
+		exit 1; \
+	fi
+	@echo "🎨 Visualizing schema: $(SCHEMA)"
+	@$(VENV_PYTHON) visualize_schema.py $(SCHEMA)
+
+cli-visualize-schema-ascii: $(VENV)/bin/activate
+	@if [ -z "$(SCHEMA)" ]; then \
+		echo "❌ Usage: make cli-visualize-schema-ascii SCHEMA=schema.json"; \
+		echo "   Example: make cli-visualize-schema-ascii SCHEMA=generated_schema.json"; \
+		exit 1; \
+	fi
+	@echo "🎨 Visualizing schema (ASCII mode): $(SCHEMA)"
+	@$(VENV_PYTHON) visualize_schema.py $(SCHEMA) --ascii
+
+# Complete workflow examples
+cli-workflow-basic: $(VENV)/bin/activate
+	@echo "🔄 Running basic MarkiTect workflow..."
+	@echo "  Step 1: Ingest document"
+	@$(MARKITECT) ingest $(SAMPLE_DOC)
+	@echo ""
+	@echo "  Step 2: Show status"
+	@$(MARKITECT) status $(SAMPLE_DOC)
+	@echo ""
+	@echo "  Step 3: Show AST statistics"
+	@$(MARKITECT) ast-stats $(SAMPLE_DOC)
+	@echo ""
+	@echo "✅ Basic workflow complete!"
+
+cli-workflow-schema: $(VENV)/bin/activate
+	@echo "🔄 Running schema generation and validation workflow..."
+	@if [ -z "$(FILE)" ]; then \
+		echo "❌ Usage: make cli-workflow-schema FILE=document.md"; \
+		echo "   Example: make cli-workflow-schema FILE=test_frontmatter.md"; \
+		exit 1; \
+	fi
+	@echo "  Step 1: Ingest document"
+	@$(MARKITECT) ingest $(FILE)
+	@echo ""
+	@echo "  Step 2: Generate schema"
+	@$(MARKITECT) generate-schema $(FILE) --output-format json > temp_schema.json
+	@echo "  Schema saved to temp_schema.json"
+	@echo ""
+	@echo "  Step 3: Validate document against generated schema"
+	@$(MARKITECT) validate $(FILE) temp_schema.json
+	@echo ""
+	@echo "  Step 4: Visualize schema"
+	@$(VENV_PYTHON) visualize_schema.py temp_schema.json --ascii
+	@echo ""
+	@echo "✅ Schema workflow complete!"
+	@echo "💡 Schema file: temp_schema.json"
+
+# Help for CLI targets
+cli-help:
+	@echo "🚀 MarkiTect CLI Usage Targets"
+	@echo "============================="
+	@echo ""
+	@echo "Document Operations:"
+	@echo "  cli-ingest [FILE=doc.md]     - Process and store markdown file"
+	@echo "  cli-status [FILE=doc.md]     - Show processing status"
+	@echo "  cli-list [OUTPUT_FORMAT=table] - List all processed documents"
+	@echo "  cli-get [FILE=doc.md]        - Retrieve processed document"
+	@echo "  cli-metadata [FILE=doc.md]   - Show document metadata"
+	@echo ""
+	@echo "Schema Operations:"
+	@echo "  cli-generate-schema [FILE=doc.md]        - Generate JSON schema"
+	@echo "  cli-validate FILE=doc.md SCHEMA=schema.json - Validate document"
+	@echo "  cli-validate-detailed FILE=doc.md SCHEMA=schema.json - Detailed validation"
+	@echo "  cli-visualize-schema SCHEMA=schema.json  - Visualize schema (colorful)"
+	@echo "  cli-visualize-schema-ascii SCHEMA=schema.json - Visualize schema (ASCII)"
+	@echo ""
+	@echo "AST Operations:"
+	@echo "  cli-ast-show [FILE=doc.md]   - Display AST structure"
+	@echo "  cli-ast-stats [FILE=doc.md]  - Show AST statistics"
+	@echo "  cli-ast-query FILE=doc.md QUERY='JSONPath' - Query AST"
+	@echo ""
+	@echo "Database Operations:"
+	@echo "  cli-query SQL='SELECT...'    - Execute SQL query"
+	@echo "  cli-schema-db               - Show database schema"
+	@echo ""
+	@echo "Cache Management:"
+	@echo "  cli-cache-info              - Show cache statistics"
+	@echo "  cli-cache-clean             - Clear all caches"
+	@echo "  cli-cache-invalidate FILE=doc.md - Invalidate specific file cache"
+	@echo ""
+	@echo "Complete Workflows:"
+	@echo "  cli-workflow-basic          - Basic ingest → status → stats workflow"
+	@echo "  cli-workflow-schema FILE=doc.md - Complete schema workflow"
+	@echo ""
+	@echo "📋 Variables:"
+	@echo "  FILE         - Target markdown file (default: $(SAMPLE_DOC))"
+	@echo "  OUTPUT_FORMAT - Output format: table, json, yaml (default: $(OUTPUT_FORMAT))"
+	@echo "  SCHEMA       - JSON schema file"
+	@echo "  SQL          - SQL query string"
+	@echo "  QUERY        - JSONPath query expression"
+	@echo ""
+	@echo "💡 Examples:"
+	@echo "  make cli-ingest FILE=my_document.md"
+	@echo "  make cli-validate FILE=doc.md SCHEMA=doc_schema.json"
+	@echo "  make cli-ast-query FILE=doc.md QUERY='$.headings[*].text'"
+	@echo "  make cli-query SQL='SELECT title FROM metadata WHERE status=\"draft\"'"
+
+# Update .PHONY for CLI targets
+.PHONY: cli-ingest cli-status cli-list cli-get cli-generate-schema cli-validate cli-validate-detailed cli-ast-show cli-ast-stats cli-ast-query cli-metadata cli-query cli-schema-db cli-cache-info cli-cache-clean cli-cache-invalidate cli-visualize-schema cli-visualize-schema-ascii cli-workflow-basic cli-workflow-schema cli-help