Implement file preservation system for output directory cleaning

- Add sophisticated file preservation functionality to _clean_output_dir()
- Support .qsgen3_preserve file with shell glob patterns for selective preservation
- Preserve shared articles and important files during site regeneration
- Maintain backward compatibility (no preserve file = complete cleaning)
- Add comprehensive documentation in how-it-works.md
- Include example preserve file (.qsgen3_preserve.example)
- Remove legacy images directory and update documentation
- Fix workflow documentation formatting issues

how-it-works.md

@@ -42,6 +42,7 @@ project-root/
 ├── bin/
 │   └── qsgen3                 # Main generator script
 ├── site.conf                 # Main configuration file
+├── .qsgen3_preserve          # Optional: File preservation patterns
 ├── content/                  # Markdown content
 │   ├── posts/               # Blog posts
 │   │   └── hello-world.md
@@ -56,7 +57,6 @@ project-root/
 ├── themes/                  # Theme directory
 │   └── theme-name/         # Individual theme
 │       ├── layouts/        # Theme-specific templates (optional)
-│       ├── static/         # Theme static assets (optional)
 │       └── css/            # Alternative theme asset location
 └── output/                 # Generated site (created by qsgen3)
     ├── index.html
@@ -128,8 +128,7 @@ themes/theme-name/
 │   └── rss.xml          # RSS template
 ├── static/              # Preferred: Standard static assets location
 │   ├── css/
-│   ├── js/
-│   └── images/
+│   └── js/
 └── css/                 # Alternative: Direct CSS location
     └── style.css
 ```
@@ -180,10 +179,7 @@ themes/my-theme/
 └── static/              # Static assets
     ├── css/
     │   └── style.css    # Main stylesheet
-    ├── js/              # JavaScript files (optional)
-    │   └── theme.js
-    └── images/          # Theme images (optional)
-        └── logo.png
+    └── js/              # JavaScript files (optional)
 ```
 
 **Option B: CSS-Only Structure**
@@ -744,8 +740,7 @@ output/
 │   └── post-name.html
 ├── static/             # All static assets
 │   ├── css/           # Stylesheets
-│   ├── js/            # JavaScript (if provided by theme)
-│   └── images/        # Images and media
+│   └── js/            # JavaScript (if provided by theme)
 └── css/               # Legacy: Index-specific CSS location
     └── theme.css      # Copy of main theme CSS for index page
 ```
@@ -870,11 +865,52 @@ Process Theme Configuration
 
 ```
 Prepare Output Directory
-├── Clean existing output directory
-├── Create fresh output directory structure
-└── Prepare for static file copying
+├── Check for .qsgen3_preserve file in project root
+├── If preserve file exists:
+│   ├── Read file patterns (shell glob patterns)
+│   ├── Create temporary backup directory
+│   ├── Find and backup matching files from output directory
+│   ├── Remove entire output directory
+│   ├── Recreate clean output directory
+│   ├── Restore preserved files maintaining directory structure
+│   └── Clean up temporary backup directory
+│   └── Remove entire output directory
+│   └── Create fresh output directory
+└── Log preservation and cleaning operations
 ```
 
+#### File Preservation System
+
+qsgen3 supports preserving specific files during the cleaning process to handle cases where content has been shared or bookmarked and should remain accessible even after title changes.
+
+**Preserve File Format (`.qsgen3_preserve`):**
+- Located in project root directory
+- One pattern per line using shell glob patterns (`*`, `?`, `[]`)
+- Lines starting with `#` are comments
+- Empty lines are ignored
+- Patterns are relative to the output directory
+
+**Example preserve patterns:**
+```bash
+# Preserve specific shared articles
+posts/my-important-shared-article.html
+posts/viral-blog-post.html
+
+# Preserve files by pattern
+posts/legacy-*.html
+archive/*
+
+# Preserve all PDFs and downloads
+*.pdf
+downloads/*
+```
+
+**Benefits:**
+- Maintains stable URLs for shared content
+- Prevents broken links when content is renamed
+- Flexible pattern matching for various preservation needs
+- Backward compatible (no preserve file = complete cleaning)
+
 ### 6. Static File Processing
 
 ```
@@ -999,6 +1035,31 @@ Complete Generation
 - Verify available disk space
 - Review path configurations for absolute vs. relative paths
 
+#### 5. File Preservation Issues
+**Symptoms**: Expected files not preserved during cleaning, or preservation not working
+**Causes**:
+- Incorrect patterns in `.qsgen3_preserve` file
+- File paths don't match patterns
+- Permission issues with temporary backup directory
+- Malformed preserve file format
+
+**Solutions**:
+- Verify patterns use shell glob syntax (`*`, `?`, `[]`)
+- Check that patterns are relative to output directory
+- Ensure `.qsgen3_preserve` file is in project root
+- Test patterns with `find output/ -name "pattern"` before adding to preserve file
+- Enable debug logging to see preservation process details
+- Verify file permissions allow temporary directory creation
+
+**Example debugging:**
+```bash
+# Test if your pattern matches files
+find output/ -name "posts/legacy-*.html"
+
+# Enable debug logging to see preservation process
+QSG_DEBUG=1 ./bin/qsgen3
+```
+
 ### Debug Logging
 
 Enable detailed logging by modifying the `_log` function or adding debug statements: